@futdevpro/fdp-agent-memory 1.1.30 → 1.1.112

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

@@ -8,6 +8,10 @@ const embedding_1 = require("../../embedding");
 const scope_reference_1 = require("../../scope-reference");
 const fam_retrieval_candidate_data_service_1 = require("./fam-retrieval-candidate.data-service");
 const fam_retrieval_suggestions_util_1 = require("./fam-retrieval-suggestions.util");
+const fam_memory_activation_util_1 = require("../_collections/fam-memory-activation.util");
+const fam_lexical_match_util_1 = require("../_collections/fam-lexical-match.util");
+const fam_memory_reactivation_control_service_1 = require("./fam-memory-reactivation.control-service");
+const fam_memory_cold_search_control_service_1 = require("./fam-memory-cold-search.control-service");
 /** A topK / lapozás abszolút plafonja (CCAP MAX_PAGE_SIZE=500; dsgn-005 §6). */
 const MAX_PAGE_SIZE = 500;
 /**
@@ -95,8 +99,57 @@ class FAM_Retrieval_ControlService {
         const relevantSet = visibleHits.filter((hit) => this.codeExactRank(hit) > 0 || hit.finalScore >= config.minScore);
         // ⑦ rendezés (finalScore desc → recency → _id asc).
         this.sortHits(relevantSet, config.scoreOrder);
+        // ⑦b R1 duplikátum-dedup (FAM-REV 2026-06-22, eval-lelet): az AZONOS-tartalmú (kereszt-repo) hitek összevonása
+        // a top-K ELŐTT — a kanonikus (legjobb-ranked) marad, a másolat-szám a `duplicateCount`-ban. A közös fájlok
+        // (`.cursor/rules` / CLAUDE.md / guideline) ne pazarolják a top-K-t 4-5 azonos másolattal. A `sortHits` UTÁN fut
+        // (a megtartott a legjobb-rangsorolt); a contentHash-mentes hitek érintetlenek.
+        const dedupedSet = FAM_Retrieval_ControlService.dedupeByContentHash(relevantSet);
         // ⑧ topK-vágás + dense-detektálás + suggestions.
-        return this.buildResult({ query, relevantSet, config, scopeExpand, detectedCodes });
+        const result = this.buildResult({ query, relevantSet: dedupedSet, config, scopeExpand, detectedCodes });
+        // dsgn-013 §4 (MAM F2) — FELIDÉZÉS-megerősítés: a ténylegesen VISSZAADOTT `memory`-hitek „új energiát kapnak"
+        // (lastRecalledAt=now, recallCount++, dormant=false). ASYNC fire-and-forget — NEM blokkolja a read választ.
+        this.reactivateReturnedMemoryHits(result.hits, config);
+        return result;
+    }
+    /**
+     * A visszaadott top-K `memory`-hitek async felidézés-megerősítése (dsgn-013 §4). Fire-and-forget (void): a read
+     * már elkészült, a felidézés-frissítés best-effort. Csak a `memory`-táras, `_id`-vel bíró hitre; üres → no-op.
+     * `memoryReactivateOnRead=false` → kikapcsolva.
+     */
+    reactivateReturnedMemoryHits(hits, config) {
+        if (!config.memoryReactivateOnRead) {
+            return;
+        }
+        const memoryIds = fam_memory_reactivation_control_service_1.FAM_MemoryReactivation_ControlService.selectMemoryIds(hits);
+        if (!memoryIds.length) {
+            return;
+        }
+        void fam_memory_reactivation_control_service_1.FAM_MemoryReactivation_ControlService.getInstance().reactivate(memoryIds, Date.now());
+    }
+    /**
+     * R1 dedup (pure): az AZONOS `contentHash`-ű hitek összevonása — az ELSŐ (a `sortHits` után legjobb-ranked) marad,
+     * a többi azonos-tartalmú másolatot beleszámoljuk a megtartott `duplicateCount`-jába. A `contentHash`-mentes hitek
+     * (pl. compact-mode projekció nélkül) NEM dedup-olódnak (mind egyedi). Sorrend-tartó.
+     */
+    static dedupeByContentHash(hits) {
+        const keptByHash = new Map();
+        const result = [];
+        for (const hit of hits) {
+            const key = hit.contentHash;
+            if (!key) {
+                result.push(hit);
+                continue;
+            }
+            const kept = keptByHash.get(key);
+            if (kept) {
+                kept.duplicateCount = (kept.duplicateCount ?? 0) + 1;
+            }
+            else {
+                keptByHash.set(key, hit);
+                result.push(hit);
+            }
+        }
+        return result;
     }
     // =========================================================================
     // ④b KÓD-EXPANZIÓ (FEAT-003) — determinisztikus link-retrieval a vektor MELLÉ
@@ -171,6 +224,7 @@ class FAM_Retrieval_ControlService {
             weight: set.weight,
             finalScore: 1.0 * set.weight,
             content: set.includeContent ? set.entry.content : undefined,
+            contentHash: set.entry.contentHash,
             kind: set.entry.kind,
             tags: set.entry.tags ?? [],
             ...this.ruleMeta(set.entry, set.table),
@@ -256,6 +310,8 @@ class FAM_Retrieval_ControlService {
             });
         }
         // ⑤ weight-szorzó: finalScore = score × (weight ?? 1); weight ≤ 0 → kizárt (nem kerül a hits közé).
+        // Improvement 2: a query lexikai term-jeit EGYSZER tokenizáljuk (a hibrid keyword-boost-hoz a toHit-ban).
+        const queryTerms = fam_lexical_match_util_1.FAM_LexicalMatch_Util.tokenize(set.query.query);
         const hits = [];
         for (const vectorHit of vectorHits) {
             const entry = byId.get(vectorHit.id);
@@ -267,12 +323,63 @@ class FAM_Retrieval_ControlService {
                 continue;
             }
             hits.push(this.toHit({
-                entry, vectorHit, table: set.table, weight,
-                importChunkWeight: set.config.importChunkWeight, includeContent: set.includeContent,
+                entry, vectorHit, table: set.table, weight, queryTerms: queryTerms,
+                importChunkWeight: set.config.importChunkWeight, importSourceWeight: set.config.importSourceWeight,
+                includeContent: set.includeContent, config: set.config, nowMs: Date.now(),
             }));
         }
+        // dsgn-013 §5.3 (MAM F3b) — COLD-search supplement: ha `memory` + engedélyezett + a hot pool kevés ERŐSEN-
+        // releváns találatot ad. FONTOS: NEM a candidate-darabszámot nézzük (a vektor-keresés ~MAX_PAGE_SIZE jelöltet ad
+        // vissza, így a `hits.length` szinte mindig nagy) — hanem az ERŐS (raw cosine ≥ relevanceFloor) hot hitek számát.
+        // Ha ezekből kevesebb mint topK van, a hot pool nem elégítette ki a query-t → a dormant készleten keresünk.
+        const strongHotHits = hits.filter((hit) => hit.score >= set.config.relevanceFloor).length;
+        if (set.table === fam_table_type_enum_1.FAM_Table.memory && set.config.memoryColdSearchEnabled && strongHotHits < set.config.topK) {
+            await this.supplementWithColdSearch(set, hits, set.query);
+        }
         return hits;
     }
+    /**
+     * A hot memória-találatok kiegészítése a dormant készletből (dsgn-013 §5.3). A cold-hiteket a `toHit`-en át
+     * (decay + faktorok) fűzzük be, a már látott `_id`-ket kiszűrve; a `weight ≤ 0` továbbra is kizárt.
+     */
+    async supplementWithColdSearch(set, hits, query) {
+        // `topK` cold-jelölt (NEM `topK - hits.length` — a `hits` itt a teljes candidate-halmaz, ~MAX_PAGE_SIZE, ami
+        // negatívot adna). A cold-hitek a NORMÁL ranking-pipeline-ba kerülnek; a végső topK-vágás (buildResult) dönt.
+        // A tag/kind prefilter UGYANAZ, mint a hot-path-é (különben kiszűrt entry-ket hozna vissza a cold-supplement).
+        const coldHits = await fam_memory_cold_search_control_service_1.FAM_MemoryColdSearch_ControlService.getInstance().search({
+            queryVector: set.queryVector,
+            scopeIdSet: set.scopeExpand.scopeIdSet ?? [],
+            topK: set.config.topK,
+            maxCandidates: set.config.memoryColdSearchMaxCandidates,
+            nowMs: Date.now(),
+            tagFilter: query.tagFilter,
+            kindFilter: query.kindFilter,
+        });
+        const seen = new Set(hits.map((hit) => hit.id));
+        const queryTerms = fam_lexical_match_util_1.FAM_LexicalMatch_Util.tokenize(query.query);
+        for (const cold of coldHits) {
+            const id = cold.entry._id;
+            const weight = cold.entry.weight ?? 1;
+            if (!id || seen.has(id) || weight <= 0) {
+                continue;
+            }
+            hits.push(this.toHit({
+                entry: cold.entry, vectorHit: { id: id, score: cold.score }, table: set.table, weight: weight, queryTerms: queryTerms,
+                importChunkWeight: set.config.importChunkWeight, importSourceWeight: set.config.importSourceWeight,
+                includeContent: set.includeContent, config: set.config, nowMs: Date.now(),
+            }));
+            seen.add(id);
+            // KRITIKUS (dsgn-013 §5.3 promóció-gap fix): a cold-talált entry vektorát AZONNAL a hot poolba is upsert-eljük.
+            // Különben — miután a reaktiváció `dormant=false`-ra állítja — az entry SEM a hot poolban (csak boot-kor
+            // hidratálódik), SEM a cold-keresésben (a `dormant:true` szűrő kizárja) nem lenne megtalálható a következő
+            // re-hidratálásig → „elérhetetlen a promóció után". A pool-upsert idempotens; a (ritka) topK-ból kieső,
+            // de még dormant entry a következő bootkor úgyis kiesik a poolból (a hidratálás-szűrő korrigálja).
+            const vector = (cold.entry.contentVector ?? []);
+            if (vector.length) {
+                embedding_1.FAM_VectorSearch_ControlService.getInstance().upsertVector({ table: set.table, id: id, vector: vector });
+            }
+        }
+    }
     /**
      * Az import-only chunkok (`chunkType:"imports"`) read-idejű rangsor-szorzója (FAM-REV-060). Egy import-sor
      * (`import { X } from "./y"`) magas cosine-t kap egy szimbólum-név query-re, de alacsony az ÉRTÉKe (csak
@@ -282,18 +389,70 @@ class FAM_Retrieval_ControlService {
     chunkTypeFactor(chunkType, importChunkWeight) {
         return chunkType === 'imports' ? importChunkWeight : 1;
     }
+    /**
+     * R2 import-source faktor (2026-06-22 eval-lelet): a `source.type:'import'` (claude-mem-import) entry-k finalScore-ja
+     * `importSourceWeight`-tel szorzódik (<1), hogy a kurált (`manual`/`agent`/scan) tanulságok a `memory`/`knowledge`
+     * táblákon FÖLÉ rangsoroljanak — az import zaja ne temesse őket. Minden NEM-import source érintetlen (×1).
+     * READ-time, a nyers `score` (relevancia) változatlan; `importSourceWeight=1` → kikapcsolva (változatlan rangsor).
+     */
+    importSourceFactor(source, importSourceWeight) {
+        return source?.type === 'import' ? importSourceWeight : 1;
+    }
+    /**
+     * Memory Activation Model decay-szorzó (dsgn-013 §3) — CSAK a `memory` táron, ha engedélyezett. A frissen/gyakran
+     * FELIDÉZETT memória felül-, a régóta érintetlen alul-rangsorol, de a `floorWeight > 0` miatt SOSEM esik ki. A
+     * `lastRecalledAt` hiányában a `__created` ideje a fallback (cold-start kegyelmi idő). Minden más tár → ×1.
+     */
+    memoryDecayFactor(entry, table, config, nowMs) {
+        if (table !== fam_table_type_enum_1.FAM_Table.memory) {
+            return 1;
+        }
+        let factor = 1;
+        if (config.memoryActivationEnabled) {
+            const createdMs = entry.__created ? new Date(entry.__created).getTime() : undefined;
+            factor = fam_memory_activation_util_1.FAM_MemoryActivation_Util.decayFactor({
+                lastRecalledAt: entry.lastRecalledAt,
+                recallCount: entry.recallCount,
+                nowMs: nowMs,
+                fallbackMs: createdMs,
+                config: {
+                    halfLifeDays: config.memoryHalfLifeDays, floorWeight: config.memoryFloorWeight,
+                    maxFrequencyBoost: config.memoryMaxFrequencyBoost, activationWeight: config.memoryActivationWeight,
+                },
+            });
+        }
+        // dsgn-013 §6 (MAM F4): a LEVÁLTOTT (superseded) régi tartalom penalizálva — a friss verzió fölébe kerül (de
+        // megmarad, cold-kereshető). A penalty az aktiváció-decay MELLÉ szorzódik (akkor is hat, ha a decay ki van kapcsolva).
+        if (entry.superseded) {
+            factor *= config.memorySupersededPenalty;
+        }
+        return factor;
+    }
     /** Egy candidate-entry + a vektor-hit → `FAM_RetrievalHit` (finalScore + denormalizált mezők). */
     toHit(set) {
         const lastModified = set.entry.__lastModified;
-        // ⑤ weight-szorzó + FAM-REV-060 import-chunk read-faktor: finalScore = score × weight × chunkTypeFactor.
+        // ⑤ weight-szorzó + FAM-REV-060 import-chunk read-faktor + R2 import-SOURCE faktor (2026-06-22 eval-lelet:
+        // a claude-mem-import zaja ne temesse a kurált tanulságokat) + dsgn-013 memory-decay (CSAK a memory táron) +
+        // Improvement 2 hibrid LEXIKAI keyword-boost (a literal-match felszínre kerül, BOOST-only) →
+        // finalScore = score × weight × chunkF × sourceF × decayF × (1 + keywordWeight × lexicalScore).
         const chunkFactor = this.chunkTypeFactor(set.entry.chunkType, set.importChunkWeight);
+        const sourceFactor = this.importSourceFactor(set.entry.source, set.importSourceWeight);
+        const decayFactor = this.memoryDecayFactor(set.entry, set.table, set.config, set.nowMs);
+        const lexicalScore = set.config.keywordWeight > 0
+            ? fam_lexical_match_util_1.FAM_LexicalMatch_Util.score(set.queryTerms, {
+                content: set.entry.content, headingPath: set.entry.headingPath, sourceFilePath: set.entry.source?.path,
+            })
+            : 0;
+        const keywordBoost = 1 + set.config.keywordWeight * lexicalScore;
         return {
             id: set.vectorHit.id,
             table: set.table,
             score: set.vectorHit.score,
             weight: set.weight,
-            finalScore: set.vectorHit.score * set.weight * chunkFactor,
+            finalScore: set.vectorHit.score * set.weight * chunkFactor * sourceFactor * decayFactor * keywordBoost,
+            lexicalScore: lexicalScore,
             content: set.includeContent ? set.entry.content : undefined,
+            contentHash: set.entry.contentHash,
             kind: set.entry.kind,
             tags: set.entry.tags ?? [],
             ...this.ruleMeta(set.entry, set.table),
@@ -324,6 +483,13 @@ class FAM_Retrieval_ControlService {
             category: rule.category,
             isActive: rule.isActive,
             applicableScopes: (rule.applicableScopes ?? []),
+            // Rules-Management MP-1 mezők a hit-en (read-DTO bővítés) — a hívó/reflex így megkülönbözteti a KURÁLT
+            // kanonikus szabályt (ruleScope/importance/userApproved/ruleId) a nyers, scannelt rules-korpusztól.
+            ruleScope: rule.ruleScope,
+            ruleScopeTopic: rule.ruleScopeTopic,
+            importance: rule.importance,
+            userApproved: rule.userApproved,
+            ruleId: rule.ruleId,
         };
     }
     // =========================================================================
@@ -488,18 +654,44 @@ class FAM_Retrieval_ControlService {
         const minScore = query.minScore ?? await this.resolveNumber(config, 'read.minScore', ctx, 0);
         const relevanceFloor = await this.resolveNumber(config, 'read.relevanceFloor', ctx, 0.5);
         const importChunkWeight = await this.resolveNumber(config, 'read.importChunkWeight', ctx, 0.4);
+        const importSourceWeight = await this.resolveNumber(config, 'read.importSourceWeight', ctx, 0.85);
+        const keywordWeight = await this.resolveNumber(config, 'read.keywordWeight', ctx, 0.6);
         const denseResultRatio = await this.resolveNumber(config, 'read.denseResultRatio', ctx, 2.0);
         const denseResultAbsMin = await this.resolveNumber(config, 'read.denseResultAbsMin', ctx, 25);
         const scoreOrderValue = (await config.resolve('read.scoreOrder', ctx)).value;
         const scoreOrder = typeof scoreOrderValue === 'string' ? scoreOrderValue : 'weighted';
+        // Memory Activation Model (dsgn-013) — a `memory.*` namespace; a decay CSAK a memory táron alkalmazódik (toHit).
+        const memoryActivationValue = (await config.resolve('memory.activationEnabled', ctx)).value;
+        const memoryActivationEnabled = memoryActivationValue !== false;
+        const memoryHalfLifeDays = await this.resolveNumber(config, 'memory.decayHalfLifeDays', ctx, 90);
+        const memoryFloorWeight = await this.resolveNumber(config, 'memory.floorWeight', ctx, 0.05);
+        const memoryMaxFrequencyBoost = await this.resolveNumber(config, 'memory.maxFrequencyBoost', ctx, 2.5);
+        const memoryActivationWeight = await this.resolveNumber(config, 'memory.activationWeight', ctx, 0.35);
+        const memoryReactivateValue = (await config.resolve('memory.reactivateOnRead', ctx)).value;
+        const memoryReactivateOnRead = memoryReactivateValue !== false;
+        const memoryColdSearchValue = (await config.resolve('memory.coldSearchEnabled', ctx)).value;
+        const memoryColdSearchEnabled = memoryColdSearchValue !== false;
+        const memoryColdSearchMaxCandidates = await this.resolveNumber(config, 'memory.coldSearchMaxCandidates', ctx, 5000);
+        const memorySupersededPenalty = await this.resolveNumber(config, 'memory.supersededPenalty', ctx, 0.25);
         return {
             topK: Math.min(topKDefault, MAX_PAGE_SIZE),
             minScore: minScore,
             relevanceFloor: relevanceFloor,
             importChunkWeight: importChunkWeight,
+            importSourceWeight: importSourceWeight,
+            keywordWeight: keywordWeight,
             denseResultRatio: denseResultRatio,
             denseResultAbsMin: denseResultAbsMin,
             scoreOrder: scoreOrder,
+            memoryActivationEnabled: memoryActivationEnabled,
+            memoryHalfLifeDays: memoryHalfLifeDays,
+            memoryFloorWeight: memoryFloorWeight,
+            memoryMaxFrequencyBoost: memoryMaxFrequencyBoost,
+            memoryActivationWeight: memoryActivationWeight,
+            memoryReactivateOnRead: memoryReactivateOnRead,
+            memoryColdSearchEnabled: memoryColdSearchEnabled,
+            memoryColdSearchMaxCandidates: memoryColdSearchMaxCandidates,
+            memorySupersededPenalty: memorySupersededPenalty,
         };
     }
     /** Egy szám-config feloldása a default-tal (a `resolve.value` lehet más típus → fallback). */

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

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RuleInjection_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_rules_data_model_1 = require("../../../_models/data-models/fam-rules.data-model");
+const embedding_1 = require("../../embedding");
+const fam_rule_injection_util_1 = require("../_collections/fam-rule-injection.util");
+const fam_rule_propagation_util_1 = require("../_collections/fam-rule-propagation.util");
+const fam_rule_scope_context_util_1 = require("../_collections/fam-rule-scope-context.util");
+/**
+ * `FAM_RuleInjection_ControlService` (Rules-Management MP-2) — a SessionStart-injektálás (+ a `read`-reflex) szerver-oldali
+ * ASSEMBLY-je: a `cwd`-ből (vagy explicit felülírásból) detektálja a tier-kontextust, prefilterezi a `fam_rules`-t a
+ * MOST érvényes TIER-ekre (`FAM_RuleInjection_Util.buildFilter`), `importance`-rangsorolja, és char-budgetbe illeszti
+ * a „(…and N more)" záró sorral. A hook így DUMB marad (csak hív + az `additionalContext`-be teszi a blokkot) — a teljes
+ * ranking/scope/budget logika ITT, szerver-oldalon, unit-tesztelhetően él (mint a `/api/doctor`).
+ */
+class FAM_RuleInjection_ControlService {
+    static _instance;
+    issuer = 'FAM_RuleInjection_ControlService';
+    static getInstance() {
+        if (!FAM_RuleInjection_ControlService._instance) {
+            FAM_RuleInjection_ControlService._instance = new FAM_RuleInjection_ControlService();
+        }
+        return FAM_RuleInjection_ControlService._instance;
+    }
+    /** A MOST érvényes always-apply rule-blokk összeállítása (detektált/felülírt kontextus alapján). */
+    async assembleInjection(input) {
+        const context = this.resolveContext(input);
+        const rules = await this.loadRulesForContext(context);
+        const assembled = fam_rule_injection_util_1.FAM_RuleInjection_Util.assemble({
+            rules: rules, budgetChars: input.budgetChars,
+        });
+        return { ...assembled, context: context };
+    }
+    /**
+     * MP-5 — a kontextusra érvényes szabályok GENERÁLT, marker-keretezett `CLAUDE.md`-blokkja (propagáció a FAM-nélküli
+     * projekt-agenteknek). Budget NÉLKÜL (minden alkalmazható szabály bekerül), dedup `ruleId`/`derivedFrom` szerint.
+     */
+    async assemblePropagation(input) {
+        const context = this.resolveContext(input);
+        const rules = await this.loadRulesForContext(context);
+        const block = fam_rule_propagation_util_1.FAM_RulePropagation_Util.wrap(fam_rule_propagation_util_1.FAM_RulePropagation_Util.renderBlock(rules));
+        return { block: block, ruleCount: fam_rule_propagation_util_1.FAM_RulePropagation_Util.dedup(rules).length, context: context };
+    }
+    /** A tier-kontextusra érvényes, aktív `rules`-entry-k betöltése injektálható view-ként (közös SSOT a két assembly-hez). */
+    async loadRulesForContext(context) {
+        const model = this.rulesModel();
+        if (!model) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.vecSearch,
+                message: 'A `fam_rules` model nincs regisztrálva (boot-előtt?).',
+                issuer: this.issuer,
+                context: { operation: 'load-rules-for-context' },
+            });
+        }
+        const filter = fam_rule_injection_util_1.FAM_RuleInjection_Util.buildFilter(context);
+        // CSAK a rangsorhoz/megjelenítéshez kellő mezők (a vektor NEM kell → könnyű lean-query).
+        const docs = await model.find(filter, {
+            content: 1, importance: 1, weight: 1, globalRule: 1, category: 1,
+            ruleScope: 1, ruleScopeTopic: 1, ruleId: 1, derivedFrom: 1, __lastModified: 1,
+        }).lean();
+        return docs.map((doc) => this.toInjectable(doc));
+    }
+    /** Explicit felülírás > `cwd`-detekció. A `projectType`/`topics`/budget mindig az inputból. */
+    resolveContext(input) {
+        const detected = fam_rule_scope_context_util_1.FAM_RuleScopeContext_Util.detect(input.cwd);
+        return {
+            isFdp: input.isFdp ?? detected.isFdp,
+            inProject: input.inProject ?? detected.inProject,
+            projectName: detected.projectName,
+            projectRoot: detected.projectRoot,
+            projectType: input.projectType ?? detected.projectType,
+            topics: input.topics ?? detected.topics,
+        };
+    }
+    /** Egy lean Mongo-doc → `FAM_InjectableRule` view. */
+    toInjectable(doc) {
+        const lastModified = doc.__lastModified;
+        return {
+            id: typeof doc._id === 'string' ? doc._id : (doc._id ? String(doc._id) : undefined),
+            content: typeof doc.content === 'string' ? doc.content : undefined,
+            importance: typeof doc.importance === 'number' ? doc.importance : undefined,
+            weight: typeof doc.weight === 'number' ? doc.weight : undefined,
+            globalRule: doc.globalRule === true,
+            category: typeof doc.category === 'string' ? doc.category : undefined,
+            ruleScope: typeof doc.ruleScope === 'string' ? doc.ruleScope : undefined,
+            ruleScopeTopic: typeof doc.ruleScopeTopic === 'string' ? doc.ruleScopeTopic : undefined,
+            ruleId: typeof doc.ruleId === 'string' ? doc.ruleId : undefined,
+            derivedFrom: typeof doc.derivedFrom === 'string' ? doc.derivedFrom : undefined,
+            lastModifiedMs: lastModified ? new Date(lastModified).getTime() : 0,
+        };
+    }
+    /** A `fam_rules` mongoose-modellje (a DS-példányosítás regisztrálja). */
+    rulesModel() {
+        new embedding_1.FAM_Entry_DataService({ dataParams: fam_rules_data_model_1.famRules_dataParams, issuer: this.issuer });
+        return mongoose_1.default.models[fam_rules_data_model_1.famRules_dataParams.dataName];
+    }
+}
+exports.FAM_RuleInjection_ControlService = FAM_RuleInjection_ControlService;

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

@@ -10,10 +10,21 @@
  * opcionális relevance-filter = BACKLOG (NEM épül).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_RetrievalSuggestions_Util = exports.FAM_RetrievalCandidate_DataService = exports.FAM_Retrieval_ControlService = void 0;
+exports.FAM_RetrievalSuggestions_Util = exports.FAM_RetrievalCandidate_DataService = exports.FAM_RuleScopeContext_Util = exports.FAM_RulePropagation_Util = exports.FAM_RuleInjection_Util = exports.FAM_RuleInjection_ControlService = exports.FAM_GlobalRule_ControlService = exports.FAM_Retrieval_ControlService = void 0;
 // SP-5.1/5.2/5.3 — a read-pipeline orchestrátor
 var fam_retrieval_control_service_1 = require("./_services/fam-retrieval.control-service");
 Object.defineProperty(exports, "FAM_Retrieval_ControlService", { enumerable: true, get: function () { return fam_retrieval_control_service_1.FAM_Retrieval_ControlService; } });
+var fam_global_rule_control_service_1 = require("./_services/fam-global-rule.control-service");
+Object.defineProperty(exports, "FAM_GlobalRule_ControlService", { enumerable: true, get: function () { return fam_global_rule_control_service_1.FAM_GlobalRule_ControlService; } });
+// Rules-Management MP-2 — always-apply rule-injektálás (SessionStart inject + read-reflex) szerver-oldali assembly
+var fam_rule_injection_control_service_1 = require("./_services/fam-rule-injection.control-service");
+Object.defineProperty(exports, "FAM_RuleInjection_ControlService", { enumerable: true, get: function () { return fam_rule_injection_control_service_1.FAM_RuleInjection_ControlService; } });
+var fam_rule_injection_util_1 = require("./_collections/fam-rule-injection.util");
+Object.defineProperty(exports, "FAM_RuleInjection_Util", { enumerable: true, get: function () { return fam_rule_injection_util_1.FAM_RuleInjection_Util; } });
+var fam_rule_propagation_util_1 = require("./_collections/fam-rule-propagation.util");
+Object.defineProperty(exports, "FAM_RulePropagation_Util", { enumerable: true, get: function () { return fam_rule_propagation_util_1.FAM_RulePropagation_Util; } });
+var fam_rule_scope_context_util_1 = require("./_collections/fam-rule-scope-context.util");
+Object.defineProperty(exports, "FAM_RuleScopeContext_Util", { enumerable: true, get: function () { return fam_rule_scope_context_util_1.FAM_RuleScopeContext_Util; } });
 // SP-5.1 ① scope + ② tag/kind Mongo-prefilter (a vektor-keresés ELŐTT)
 var fam_retrieval_candidate_data_service_1 = require("./_services/fam-retrieval-candidate.data-service");
 Object.defineProperty(exports, "FAM_RetrievalCandidate_DataService", { enumerable: true, get: function () { return fam_retrieval_candidate_data_service_1.FAM_RetrievalCandidate_DataService; } });

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

@@ -54,5 +54,81 @@ class FAM_ScopeMaintenance_Util {
             },
         };
     }
+    /**
+     * 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;