@futdevpro/fdp-agent-memory 1.1.21 → 1.1.112

package/build/src/_modules/retrieval/_collections/fam-lexical-match.util.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_LexicalMatch_Util = void 0;
+/**
+ * `FAM_LexicalMatch_Util` (Hybrid Lexical Retrieval, Improvement 2) — **pure** lexikai (keyword/term-overlap) jel a
+ * retrieval-rangsorhoz. A tiszta-vektor `read` ELVÉTI a literal-keyword választ (eval-lelet: a „port naming" memória
+ * kiesett a top-12-ből, a `grep` azonnal hozta), mert az entry nyers koszinusza alacsony a query-megfogalmazásra.
+ * Ez a util a query DISZTINKTÍV term-jeinek átfedését méri az entry kereshető szövegével (content + heading + forrás-út),
+ * 0..1 skálán — a `toHit` ezt **multiplikatívan, BOOST-only** fűzi a finalScore-ba (`× (1 + keywordWeight × lexical)`),
+ * így a literal-match felszínre kerül, de a tiszta-szemantikus találat SOHA nem süllyed (lexical 0 → ×1).
+ */
+class FAM_LexicalMatch_Util {
+    /** A heading/forrás-út egyezés extra súlya (erős „erről szól" jel): a base-átfedés MELLÉ adódik, 1-re vágva. */
+    static TITLE_PATH_BONUS = 0.3;
+    /** Minimális token-hossz (az 1-betűs/számjegyes zaj kihagyva). */
+    static MIN_TOKEN_LEN = 2;
+    /** Tömör stopword-szett (EN + HU — a korpusz Hunglish) — ezek NEM disztinktívek, kihagyva a query-termekből. */
+    static STOPWORDS = new Set([
+        // EN
+        'the', 'a', 'an', 'of', 'to', 'in', 'on', 'at', 'by', 'for', 'and', 'or', 'is', 'are', 'be', 'as', 'we',
+        'do', 'how', 'what', 'with', 'from', 'this', 'that', 'it', 'its', 'our', 'your', 'can', 'not', 'no', 'so',
+        'if', 'then', 'else', 'into', 'out', 'up', 'down', 'about', 'which', 'who', 'when', 'where', 'why', 'use',
+        // HU
+        'az', 'és', 'es', 'hogy', 'van', 'egy', 'nem', 'igen', 'de', 'mert', 'ami', 'amit', 'ez', 'azt', 'volt',
+        'lesz', 'kell', 'meg', 'el', 'be', 'ki', 'le', 'fel', 'rá', 'ra', 'mi', 'te', 'ő', 'mit', 'hol',
+    ]);
+    /** Tokenizálás: kisbetűsít, nem-alfanumerikuson tör, stopword + rövid token kihagyva, DEDUP (Set). */
+    static tokenize(text) {
+        const terms = new Set();
+        if (!text) {
+            return terms;
+        }
+        for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+            if (raw.length >= FAM_LexicalMatch_Util.MIN_TOKEN_LEN && !FAM_LexicalMatch_Util.STOPWORDS.has(raw)) {
+                terms.add(raw);
+            }
+        }
+        return terms;
+    }
+    /**
+     * Lexikai átfedés-score (0..1): a `queryTerms` hányad része van jelen az entry kereshető szövegében.
+     * `content`-egyezés = base-átfedés; `headingPath`/`sourceFilePath`-egyezés = + `TITLE_PATH_BONUS` súly (1-re vágva).
+     * Üres query-term-halmaz → 0 (nincs jel → nincs boost). PURE.
+     */
+    static score(queryTerms, entry) {
+        if (!queryTerms.size) {
+            return 0;
+        }
+        const titlePathText = `${(entry.headingPath ?? []).join(' ')} ${entry.sourceFilePath ?? ''}`;
+        const titlePathTerms = FAM_LexicalMatch_Util.tokenize(titlePathText);
+        const contentTerms = FAM_LexicalMatch_Util.tokenize(entry.content);
+        let baseMatched = 0;
+        let titleMatched = 0;
+        for (const term of queryTerms) {
+            const inTitlePath = titlePathTerms.has(term);
+            if (contentTerms.has(term) || inTitlePath) {
+                baseMatched++;
+            }
+            if (inTitlePath) {
+                titleMatched++;
+            }
+        }
+        const total = queryTerms.size;
+        const base = baseMatched / total;
+        const titleBonus = (titleMatched / total) * FAM_LexicalMatch_Util.TITLE_PATH_BONUS;
+        return Math.min(1, base + titleBonus);
+    }
+}
+exports.FAM_LexicalMatch_Util = FAM_LexicalMatch_Util;

package/build/src/_modules/retrieval/_collections/fam-memory-activation.util.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_MemoryActivation_Util = void 0;
+/**
+ * `FAM_MemoryActivation_Util` (dsgn-013 §2) — a Memory Activation Model **lazy-decay magja**, PURE. A `memory`-tár
+ * retrieval-rangsorához számolja a felidézés-alapú aktivációs szorzót: a frissen/gyakran felidézett memória
+ * felül-, a régóta érintetlen alul-rangsorol — DE sosem tűnik el (`floorWeight > 0`), csak kisebb a súlya.
+ *
+ * **Emberi-agy-analógia:** a felidézés megerősít (`frequencyBoost`, testing effect), a nem-felidézés lassan
+ * degradál (`recencyFactor`, Ebbinghaus-felejtési görbe). NINCS `Date.now()` a magban — a `nowMs` injektált
+ * (workflow-determinizmus + unit-stabilitás).
+ */
+class FAM_MemoryActivation_Util {
+    /** Egy nap ms-ben. */
+    static MS_PER_DAY = 86_400_000;
+    /**
+     * A nyers aktiváció-összetevők (recency × frequency) egy memória-entryre. A `lastRecalledAt` hiánya → a `fallbackMs`
+     * (tipikusan a létrehozás ideje: cold-start kegyelmi idő). A `nowMs − lastRecalledAt` negatívra is védett (→ 0 nap).
+     */
+    static activation(set) {
+        const lastRecalled = typeof set.lastRecalledAt === 'number' ? set.lastRecalledAt : (set.fallbackMs ?? set.nowMs);
+        const ageDays = Math.max(0, set.nowMs - lastRecalled) / FAM_MemoryActivation_Util.MS_PER_DAY;
+        const halfLife = set.halfLifeDays > 0 ? set.halfLifeDays : 1;
+        const recencyFactor = Math.pow(0.5, ageDays / halfLife);
+        const recallCount = Math.max(0, set.recallCount ?? 0);
+        // CAP (eval-lelet): a nyers `1 + log2(1+recallCount)` korlátlan → plafonozzuk, hogy ne nyomja el a relevanciát.
+        const rawFrequencyBoost = 1 + Math.log2(1 + recallCount);
+        const frequencyBoost = (typeof set.maxFrequencyBoost === 'number' && set.maxFrequencyBoost > 0)
+            ? Math.min(rawFrequencyBoost, set.maxFrequencyBoost)
+            : rawFrequencyBoost;
+        return { recencyFactor: recencyFactor, frequencyBoost: frequencyBoost, activation: recencyFactor * frequencyBoost };
+    }
+    /**
+     * A retrieval-rankinghoz használt **decay-szorzó** (dsgn-013 §3): `max(floorWeight, activation)`. Ezt szorozza a
+     * `finalScore` a `memory`-táron (a `chunkFactor`/`sourceFactor` mellé). A `floorWeight` az alsó korlát — a régi
+     * memória lesüllyed, de a vektor-keresésben még megtalálható (a `weight ≤ 0 → kizárt` szabályt NEM lépi át).
+     */
+    static decayFactor(set) {
+        const activation = FAM_MemoryActivation_Util.activation({
+            lastRecalledAt: set.lastRecalledAt, recallCount: set.recallCount, nowMs: set.nowMs,
+            halfLifeDays: set.config.halfLifeDays, fallbackMs: set.fallbackMs,
+            maxFrequencyBoost: set.config.maxFrequencyBoost,
+        });
+        const raw = Math.max(set.config.floorWeight, activation.activation);
+        // TEMPER (eval-lelet 2026-06-25): a nyers szorzót az 1 felé húzzuk (`1 + α·(raw−1)`) → az aktiváció FINOMAN
+        // modulál, a koszinusz-relevancia dominál. α≥1 vagy hiányzó → változatlan (régi viselkedés, back-compat).
+        const alpha = set.config.activationWeight;
+        if (typeof alpha === 'number' && alpha >= 0 && alpha < 1) {
+            return 1 + alpha * (raw - 1);
+        }
+        return raw;
+    }
+    /**
+     * DORMANT-szabály (dsgn-013 §5.1, PURE) — egy memória ALVÓ-jelölt, ha **régóta nem-felidézett** (`ageDays ≥
+     * minAgeDays`) ÉS **ritkán-felidézett** (`recallCount < maxRecallCount`). A sokszor-felidézett (gyakran használt)
+     * memória SOHA nem dormant (a `recallCount`-gát védi). A `lastRecalledAt` hiányában a `fallbackMs` (létrehozás).
+     * Ez a szabály Mongo-kifejezhető (a `sweep` ugyanezt az age+recall kaput használja → konzisztens).
+     */
+    static isDormant(set) {
+        const lastRecalled = typeof set.lastRecalledAt === 'number' ? set.lastRecalledAt : (set.fallbackMs ?? set.nowMs);
+        const ageDays = Math.max(0, set.nowMs - lastRecalled) / FAM_MemoryActivation_Util.MS_PER_DAY;
+        const recallCount = Math.max(0, set.recallCount ?? 0);
+        return ageDays >= set.minAgeDays && recallCount < set.maxRecallCount;
+    }
+}
+exports.FAM_MemoryActivation_Util = FAM_MemoryActivation_Util;

package/build/src/_modules/retrieval/_collections/fam-rule-injection.util.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RuleInjection_Util = void 0;
+const fam_rule_scope_type_enum_1 = require("../../../_enums/fam-rule-scope.type-enum");
+/**
+ * `FAM_RuleInjection_Util` (Rules-Management MP-2) — a rule-injektálás **pure** (DB-/hálózat-mentes) magja:
+ * ① a kontextusból Mongo-prefilter `$or` (mely TIER-ek injektálódnak MOST), ② determinisztikus, `importance`-elsődleges
+ * rangsor, ③ char-budget-fit + „(…and N more rules not shown)" záró sor. A control-service végzi a DB-query-t és
+ * delegál ide — így a kontraktus (mely tier, milyen sorrend, hol vágunk) önállóan unit-tesztelhető.
+ *
+ * **Záró sor (user-FR):** valahányszor a budget miatt szabály marad ki, a blokk végén JELEZNI kell, hogy van több
+ * (NEM-aggresszív injektálás: a core befér, a többi „létezik" jelzéssel) — így az agent tudja, hogy `read`-elhet továbbiakat.
+ */
+class FAM_RuleInjection_Util {
+    /** Default char-budget az injektált blokkra (a hook felül tudja írni). Tömör core ~ ennyibe fér. */
+    static DEFAULT_BUDGET_CHARS = 6000;
+    /** A `globalRule:true` legacy hard-rule effektív fontossága, ha nincs explicit `importance`. */
+    static LEGACY_GLOBAL_IMPORTANCE = 90;
+    /** Importance-default explicit érték nélkül (közepes — a globalRule-legacy fölött, nem-jelölt alatt). */
+    static DEFAULT_IMPORTANCE = 50;
+    /**
+     * A MOST érvényes TIER-ekhez tartozó Mongo-prefilter `$or` ágai (PURE). A `global` MINDIG; a többi a
+     * kontextustól függ. A legacy `globalRule:true` (MP-4 átsorolás ELŐTT) is bekerül — így a meglévő curated-core
+     * a migráció alatt is injektálódik. A `trigger`-tier SZÁNDÉKOSAN kimarad az always-on injektálásból (on-demand `read`).
+     */
+    static scopeOrBranches(context) {
+        const ors = [
+            { ruleScope: fam_rule_scope_type_enum_1.FAM_RuleScope.global },
+            { globalRule: true },
+        ];
+        if (context.isFdp) {
+            ors.push({ ruleScope: fam_rule_scope_type_enum_1.FAM_RuleScope.fdpGlobal });
+        }
+        if (context.inProject) {
+            ors.push({ ruleScope: fam_rule_scope_type_enum_1.FAM_RuleScope.projectInternal });
+            if (context.projectType) {
+                ors.push({ ruleScope: fam_rule_scope_type_enum_1.FAM_RuleScope.projectType, ruleScopeTopic: context.projectType });
+            }
+        }
+        else {
+            ors.push({ ruleScope: fam_rule_scope_type_enum_1.FAM_RuleScope.workspaceRoot });
+        }
+        for (const topic of context.topics ?? []) {
+            ors.push({ ruleScope: fam_rule_scope_type_enum_1.FAM_RuleScope.trigger, ruleScopeTopic: topic });
+        }
+        return ors;
+    }
+    /** A teljes injektálás-prefilter (soft-delete + aktív + scope-`$or`). */
+    static buildFilter(context) {
+        return {
+            _deleted: null,
+            isActive: { $ne: false },
+            $or: FAM_RuleInjection_Util.scopeOrBranches(context),
+        };
+    }
+    /** Effektív fontosság (0–100): explicit `importance`, vagy legacy-globalRule → 90, egyébként 50. Clamp 0..100. */
+    static effectiveImportance(rule) {
+        const raw = typeof rule.importance === 'number'
+            ? rule.importance
+            : (rule.globalRule ? FAM_RuleInjection_Util.LEGACY_GLOBAL_IMPORTANCE : FAM_RuleInjection_Util.DEFAULT_IMPORTANCE);
+        return Math.max(0, Math.min(100, raw));
+    }
+    /**
+     * Determinisztikus injektálás-komparátor: effektív-importance DESC → weight DESC → category ASC →
+     * recency (`lastModifiedMs`) DESC → `id` ASC. A teljes lánc stabil, reprodukálható sorrendet ad.
+     */
+    static compare(a, b) {
+        const impDiff = FAM_RuleInjection_Util.effectiveImportance(b) - FAM_RuleInjection_Util.effectiveImportance(a);
+        if (impDiff !== 0) {
+            return impDiff;
+        }
+        const weightDiff = (b.weight ?? 1) - (a.weight ?? 1);
+        if (weightDiff !== 0) {
+            return weightDiff;
+        }
+        const catA = a.category ?? '';
+        const catB = b.category ?? '';
+        if (catA !== catB) {
+            return catA < catB ? -1 : 1;
+        }
+        const recA = a.lastModifiedMs ?? 0;
+        const recB = b.lastModifiedMs ?? 0;
+        if (recA !== recB) {
+            return recB - recA;
+        }
+        return (a.id ?? '') < (b.id ?? '') ? -1 : 1;
+    }
+    /** A jelöltek rangsorolva (új tömb; nem mutál). */
+    static rank(rules) {
+        return [...rules].sort(FAM_RuleInjection_Util.compare);
+    }
+    /**
+     * A rangsorolt szabályok char-budget-fit összefűzése + „(…and N more)" záró sor. Greedy: rangsor-sorrendben
+     * addig vesz fel, amíg a következő szabály content-je (a `separator`-ral) belefér. Ha a legelső sem fér, akkor is
+     * felveszi (legalább a legfontosabb core menjen). A footer csak akkor van, ha tényleg maradt ki.
+     */
+    static assemble(input) {
+        const budget = input.budgetChars && input.budgetChars > 0 ? input.budgetChars : FAM_RuleInjection_Util.DEFAULT_BUDGET_CHARS;
+        const sep = input.separator ?? '\n\n';
+        // CSAK a content-tel bíró szabályok a populáció — az üres-content entry NEM „budget miatt kihagyott" (nincs mit injektálni).
+        const ranked = FAM_RuleInjection_Util.rank(input.rules)
+            .filter((rule) => (rule.content ?? '').trim().length > 0);
+        const total = ranked.length;
+        const parts = [];
+        let used = 0;
+        let included = 0;
+        for (const rule of ranked) {
+            const text = (rule.content ?? '').trim();
+            const addLen = text.length + (parts.length ? sep.length : 0);
+            if (used + addLen > budget && included > 0) {
+                break; // budget-stop (de a legelső MINDIG befér — included>0 guard)
+            }
+            parts.push(text);
+            used += addLen;
+            included++;
+        }
+        const omitted = total - included;
+        const footer = omitted > 0
+            ? `(…and ${omitted} more rule${omitted === 1 ? '' : 's'} not shown — \`read\` the \`rules\` table for the rest.)`
+            : undefined;
+        const block = footer ? `${parts.join(sep)}${parts.length ? sep : ''}${footer}` : parts.join(sep);
+        return { block: block, includedCount: included, omittedCount: omitted, totalCount: total, footer: footer };
+    }
+}
+exports.FAM_RuleInjection_Util = FAM_RuleInjection_Util;

package/build/src/_modules/retrieval/_collections/fam-rule-propagation.util.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RulePropagation_Util = void 0;
+const fam_rule_scope_type_enum_1 = require("../../../_enums/fam-rule-scope.type-enum");
+const fam_rule_injection_util_1 = require("./fam-rule-injection.util");
+/**
+ * `FAM_RulePropagation_Util` (Rules-Management MP-5) — **pure** renderer + file-merger: a FAM-ban tárolt szabályokból
+ * egy generált, marker-keretezett blokkot képez a projekt-`CLAUDE.md`-be, hogy a **FAM-NÉLKÜLI** projekt-agentek is
+ * lássák a szabályokat. Dedup: `ruleId` (+ `derivedFrom` provenance) → 1 canonical entry/szabály (nem N duplikátum);
+ * `ruleId` nélkül content-alapú. A blokk scope szerint csoportosított + `importance` szerint rendezett.
+ *
+ * A merge IDEMPOTENS: a markerek között CSERÉL (update-if-stale), hiányzó marker → append (create-if-missing). A markeren
+ * KÍVÜLI kézi tartalmat sosem érinti.
+ */
+class FAM_RulePropagation_Util {
+    static MARKER_START = '<!-- FAM-RULES (generated — do not edit by hand) -->';
+    static MARKER_END = '<!-- /FAM-RULES -->';
+    /** A scope-csoportok megjelenítési sorrendje + címe. */
+    static SCOPE_ORDER = [
+        { scope: fam_rule_scope_type_enum_1.FAM_RuleScope.global, title: 'Global (every system)' },
+        { scope: fam_rule_scope_type_enum_1.FAM_RuleScope.fdpGlobal, title: 'FDP-global (FDP ecosystem)' },
+        { scope: fam_rule_scope_type_enum_1.FAM_RuleScope.workspaceRoot, title: 'Workspace-root' },
+        { scope: fam_rule_scope_type_enum_1.FAM_RuleScope.projectInternal, title: 'Project-internal' },
+        { scope: fam_rule_scope_type_enum_1.FAM_RuleScope.projectType, title: 'Project-type' },
+        { scope: fam_rule_scope_type_enum_1.FAM_RuleScope.trigger, title: 'Trigger (context-specific)' },
+    ];
+    /**
+     * Dedup `ruleId` szerint: azonos `ruleId` → a legmagasabb effektív-importance-ű marad (a `derivedFrom`-propagált
+     * másolatok beolvadnak). `ruleId` nélküli szabályok content-prefix szerint deduplikálódnak. Új tömb (nem mutál).
+     */
+    static dedup(rules) {
+        const byKey = new Map();
+        for (const rule of rules) {
+            const key = rule.ruleId && rule.ruleId.trim().length
+                ? `id:${rule.ruleId.trim()}`
+                : `content:${(rule.content ?? '').trim().slice(0, 120)}`;
+            const existing = byKey.get(key);
+            if (!existing || fam_rule_injection_util_1.FAM_RuleInjection_Util.effectiveImportance(rule) > fam_rule_injection_util_1.FAM_RuleInjection_Util.effectiveImportance(existing)) {
+                byKey.set(key, rule);
+            }
+        }
+        return [...byKey.values()];
+    }
+    /** A generált blokk BELSŐ szövege (markerek nélkül): scope-csoportok, importance-rendezve. */
+    static renderBlock(rules, opts) {
+        const deduped = FAM_RulePropagation_Util.dedup(rules);
+        const lines = [];
+        lines.push(opts?.heading ?? '## FDP Agent Hard-Rules (synced from FAM)');
+        lines.push('');
+        lines.push('> Generated from the canonical rule set. Edit the rules in `documentations/rules/`, not here.');
+        for (const group of FAM_RulePropagation_Util.SCOPE_ORDER) {
+            const inScope = deduped
+                .filter((rule) => rule.ruleScope === group.scope)
+                .sort(fam_rule_injection_util_1.FAM_RuleInjection_Util.compare);
+            if (!inScope.length) {
+                continue;
+            }
+            lines.push('');
+            lines.push(`### ${group.title}`);
+            for (const rule of inScope) {
+                lines.push(FAM_RulePropagation_Util.formatRule(rule));
+            }
+        }
+        return lines.join('\n');
+    }
+    /** Egy szabály egy-soros bullet-je: `- **Title** (importance) — body`. */
+    static formatRule(rule) {
+        const content = (rule.content ?? '').trim();
+        const titleMatch = content.match(/^#{1,6}\s+(.+)$/m);
+        const title = titleMatch ? titleMatch[1].trim() : (rule.ruleId ?? 'rule');
+        const body = content.replace(/^#{1,6}\s+.+$/m, '').replace(/\s+/g, ' ').trim();
+        const importance = fam_rule_injection_util_1.FAM_RuleInjection_Util.effectiveImportance(rule);
+        return `- **${title}** (${importance})${body ? ` — ${body}` : ''}`;
+    }
+    /** A blokk marker-kerettel. */
+    static wrap(block) {
+        return `${FAM_RulePropagation_Util.MARKER_START}\n${block}\n${FAM_RulePropagation_Util.MARKER_END}`;
+    }
+    /**
+     * A wrapped blokk IDEMPOTENS beillesztése egy fájl-tartalomba: ha a markerek megvannak → a köztük lévő rész CSERÉL
+     * (a markeren kívüli kézi tartalom marad); ha nincs → a fájl VÉGÉRE fűzi (egy elválasztó üres sorral). Új string.
+     */
+    static mergeIntoFile(fileContent, wrappedBlock) {
+        const startIdx = fileContent.indexOf(FAM_RulePropagation_Util.MARKER_START);
+        const endIdx = fileContent.indexOf(FAM_RulePropagation_Util.MARKER_END);
+        if (startIdx >= 0 && endIdx > startIdx) {
+            const before = fileContent.slice(0, startIdx);
+            const after = fileContent.slice(endIdx + FAM_RulePropagation_Util.MARKER_END.length);
+            return `${before}${wrappedBlock}${after}`;
+        }
+        const base = fileContent.replace(/\s+$/, '');
+        return base.length ? `${base}\n\n${wrappedBlock}\n` : `${wrappedBlock}\n`;
+    }
+}
+exports.FAM_RulePropagation_Util = FAM_RulePropagation_Util;

package/build/src/_modules/retrieval/_collections/fam-rule-scope-context.util.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RuleScopeContext_Util = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const fam_project_discovery_util_1 = require("../../../_collections/fam-project-discovery.util");
+/**
+ * `FAM_RuleScopeContext_Util` (MP-2) — a `cwd`-ből **pure** (csak fs-stat/olvasás, nincs hálózat/DB) levezeti, mely
+ * rule-TIER-ek érvényesek. Felfelé sétál a `cwd`-ből a legközelebbi projekt-gyökérig (`isProjectRoot`):
+ * - **inProject** = találtunk projekt-gyökeret a fán (a multi-projekt workspace-root NEM projekt-gyökér — nincs
+ *   `package.json`/`.git` rajta —, így sosem téveszt projektnek).
+ * - **isFdp** = a legközelebbi projekt `package.json`-ja `@futdevpro` (név VAGY bármely dependency) → FDP-repo.
+ *
+ * A `projectType` SZÁNDÉKOSAN nem auto-detektált itt (a kanonikus projekt-típus-taxonómiát MP-4/MP-7 rögzíti) —
+ * explicit kontextusból jön. A `cwd` hiányában minden `false` (csak a `global` tier injektál → mindig helyes).
+ */
+class FAM_RuleScopeContext_Util {
+    /** A felfelé-séta maximum mélysége (defenzív korlát; a tipikus projekt-mélység jóval ez alatt van). */
+    static MAX_WALK_UP = 12;
+    /** A `cwd`-ből levezetett kontextus (pure). */
+    static detect(cwd) {
+        if (!cwd || !cwd.trim()) {
+            return { isFdp: false, inProject: false };
+        }
+        const projectRoot = FAM_RuleScopeContext_Util.nearestProjectRoot(cwd);
+        if (!projectRoot) {
+            return { isFdp: false, inProject: false };
+        }
+        return {
+            isFdp: FAM_RuleScopeContext_Util.isFdpProject(projectRoot),
+            inProject: true,
+            projectName: fam_project_discovery_util_1.FAM_ProjectDiscovery_Util.projectName(projectRoot),
+            projectRoot: projectRoot,
+        };
+    }
+    /** A legközelebbi projekt-gyökér a `cwd`-ből felfelé (`isProjectRoot`), vagy `undefined`. */
+    static nearestProjectRoot(cwd) {
+        let dir = cwd;
+        for (let i = 0; i < FAM_RuleScopeContext_Util.MAX_WALK_UP; i++) {
+            if (fam_project_discovery_util_1.FAM_ProjectDiscovery_Util.isProjectRoot(dir)) {
+                return dir;
+            }
+            const parent = (0, path_1.dirname)(dir);
+            if (parent === dir) {
+                break; // elértük a fs-gyökeret
+            }
+            dir = parent;
+        }
+        return undefined;
+    }
+    /** FDP-projekt-e: a `package.json` `name` VAGY bármely dependency-kulcs `@futdevpro/`-val kezdődik. */
+    static isFdpProject(projectRoot) {
+        try {
+            const pkgPath = (0, path_1.join)(projectRoot, 'package.json');
+            if (!(0, fs_1.existsSync)(pkgPath)) {
+                return false;
+            }
+            const pkg = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf-8'));
+            if (typeof pkg.name === 'string' && pkg.name.startsWith('@futdevpro/')) {
+                return true;
+            }
+            return [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies].some((deps) => deps && typeof deps === 'object'
+                && Object.keys(deps).some((key) => key.startsWith('@futdevpro/')));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** A projekt bare-neve (a `nearestProjectRoot` basenameje) — segéd a teszteknek/diagnosztikának. */
+    static basenameOf(path) {
+        return (0, path_1.basename)(path);
+    }
+}
+exports.FAM_RuleScopeContext_Util = FAM_RuleScopeContext_Util;

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

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_GlobalRule_ControlService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const scope_reference_1 = require("../../scope-reference");
+const embedding_1 = require("../../embedding");
+const fam_rules_data_model_1 = require("../../../_models/data-models/fam-rules.data-model");
+/**
+ * `FAM_GlobalRule_ControlService` (user-FR 2026-06-22 — a FAM fő feature-je: globális hard-rule öröklés) — a
+ * `rules`-bejegyzések `globalRule` flagjének BE-/KIkapcsolása. A `globalRule:true` bejegyzéseket a retrieval
+ * MINDEN scope-szűrt `rules`-lekérdezésbe behúzza (scope-tól függetlenül) → a workspace-szintű hard-rules
+ * (E2E-hard-rule, always-master, naming/import-konvenciók) öröklődnek minden al-scope-ba.
+ *
+ * A jelölés a Mongo `fam_rules`-on `updateMany` (a flag NEM érinti a vektor-poolt → nincs re-hidratálás, a
+ * következő lekérdezés már a frissített prefilteren megy). Szelektor: `ids` VAGY `scopeFilter` (a scope subtree
+ * minden rule-ja) VAGY `tags`. `dryRun` → csak az érintett-szám.
+ */
+class FAM_GlobalRule_ControlService {
+    static _instance;
+    issuer = 'FAM_GlobalRule_ControlService';
+    static getInstance() {
+        if (!FAM_GlobalRule_ControlService._instance) {
+            FAM_GlobalRule_ControlService._instance = new FAM_GlobalRule_ControlService();
+        }
+        return FAM_GlobalRule_ControlService._instance;
+    }
+    /** A `globalRule` flag beállítása a szelektornak megfelelő `rules`-bejegyzéseken (`updateMany`). */
+    async setGlobalRule(input) {
+        const global = input.global !== false;
+        const dryRun = input.dryRun === true;
+        const filter = { _deleted: null };
+        const ors = [];
+        if (input.ids && input.ids.length) {
+            ors.push({ _id: { $in: input.ids } });
+        }
+        if (input.tags && input.tags.length) {
+            ors.push({ tags: { $in: input.tags } });
+        }
+        if (input.scopeFilter && input.scopeFilter.length) {
+            const expand = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().expandForRead(input.scopeFilter);
+            if (expand.scopeIdSet && expand.scopeIdSet.length) {
+                ors.push({ 'scopePath.scopeId': { $in: expand.scopeIdSet } });
+            }
+        }
+        if (!ors.length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                message: 'A `set_global_rule` szelektor KÖTELEZŐ: adj meg `ids` VAGY `scopeFilter` VAGY `tags` mezőt.',
+                issuer: this.issuer,
+                context: { operation: 'set-global-rule' },
+            });
+        }
+        filter.$or = ors;
+        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: 'set-global-rule' },
+            });
+        }
+        const matched = await model.countDocuments(filter);
+        let modified = 0;
+        if (!dryRun && matched > 0) {
+            const res = await model.updateMany(filter, { $set: { globalRule: global } });
+            modified = res.modifiedCount ?? 0;
+            fsm_dynamo_1.DyFM_Log.info(`[FAM globalRule] ${modified} rules-bejegyzés globalRule=${global} (matched ${matched}).`);
+        }
+        return { operation: 'set_global_rule', dryRun: dryRun, global: global, matched: matched, modified: modified };
+    }
+    /** 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_GlobalRule_ControlService = FAM_GlobalRule_ControlService;

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

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_MemoryColdSearch_ControlService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const embedding_1 = require("../../embedding");
+const fam_memory_data_model_1 = require("../../../_models/data-models/fam-memory.data-model");
+/**
+ * `FAM_MemoryColdSearch_ControlService` (dsgn-013 §5.3, MAM F3b) — az ALVÓ (`dormant`) memóriák COLD keresése. A
+ * dormant entry-k NINCSENEK a hot LVS-poolban (§5.2), ezért a normál read nem találja őket. Amikor a hot memória-
+ * találatok KEVESEK (a query a hot készletből nincs kielégítve), ez a szolgáltatás a dormant készleten Mongo-oldali
+ * koszinusz-keresést futtat (lassabb, de teljes), és a megtalált top-K-t **REAKTIVÁLJA** (`dormant=false` → a
+ * következő (re)hidratáláskor visszakerül a hot készletbe). „A dormant nem tűnik el, csak nincs a gyors úton."
+ *
+ * **Korlátozott:** a dormant scan a `maxCandidates`-re vágott (biztonsági memóriakorlát); a `scopeIdSet`-re szűkített.
+ */
+class FAM_MemoryColdSearch_ControlService {
+    static _instance;
+    issuer = 'FAM_MemoryColdSearch_ControlService';
+    static getInstance() {
+        if (!FAM_MemoryColdSearch_ControlService._instance) {
+            FAM_MemoryColdSearch_ControlService._instance = new FAM_MemoryColdSearch_ControlService();
+        }
+        return FAM_MemoryColdSearch_ControlService._instance;
+    }
+    /**
+     * Cold-keresés a dormant memórián. Betölti a scope-szűrt dormant entry-ket (lean, vektorral, `maxCandidates`-ig),
+     * koszinusz-rangsort számol a query-vektorral, a top-K-t REAKTIVÁLJA, és visszaadja a `FAM_ColdHit`-eket. Üres
+     * query-vektor / nincs dormant / hiba → üres lista (best-effort, a read-et nem buktatja).
+     */
+    async search(set) {
+        if (!set.queryVector.length || set.topK <= 0) {
+            return [];
+        }
+        try {
+            const model = this.memoryModel();
+            if (!model) {
+                return [];
+            }
+            const filter = FAM_MemoryColdSearch_ControlService.buildColdFilter(set);
+            const dormant = await model.find(filter).limit(Math.max(1, set.maxCandidates)).lean().exec();
+            // KRITIKUS (_id-konzisztencia, ld. streamHydratableVectors): a `.lean()` NYERS ObjectId `_id`-t ad, de a
+            // hit-id-knak STRING-nek kell lenniük (a hot-hitek pool-/findDataList-id-jával egyezően) — különben a dedup
+            // (`seen.has`), a reaktiváció (`typeof id === 'string'` szűrő) és a wire-szerializáció elromlik.
+            for (const entry of dormant) {
+                if (entry._id) {
+                    entry._id = String(entry._id);
+                }
+            }
+            // A reaktiváció/promóció NEM itt történik: a hívó (`reactivateReturnedMemoryHits`) a VÉGSŐ, topK-vágott
+            // result.hits-re fut → CSAK a ténylegesen visszaadott cold-hit promótálódik (dormant=false) + kap +1 recall,
+            // EGYSZER (nincs dupla-számolás, és a topK-ból kieső cold-jelölt NEM promótálódik fölöslegesen).
+            return FAM_MemoryColdSearch_ControlService.rankByCosine(set.queryVector, dormant, set.topK);
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM memoryColdSearch] cold-keresés sikertelen (best-effort): ${error?.message}`);
+            return [];
+        }
+    }
+    /**
+     * Koszinusz-rangsor (PURE, tesztelhető): a dimenzió-egyező vektorú entry-kre score-t számol, a 0 ≤ score-t kiejti,
+     * desc rendez, top-K. (A l2-normalizált vektorokon a koszinusz a valódi similarity — BFR-AM-007.)
+     */
+    static rankByCosine(queryVector, entries, topK) {
+        const hits = [];
+        for (const entry of entries) {
+            const vector = (entry.contentVector ?? []);
+            if (vector.length !== queryVector.length) {
+                continue;
+            }
+            const score = FAM_MemoryColdSearch_ControlService.cosineSimilarity(queryVector, vector);
+            if (score > 0) {
+                hits.push({ entry: entry, score: score });
+            }
+        }
+        hits.sort((a, b) => b.score - a.score);
+        return hits.slice(0, Math.max(0, topK));
+    }
+    /**
+     * A cold-keresés Mongo-filtere (PURE, tesztelhető): dormant + completed + AKTÍV (`_deleted: null`) + scope/tag/kind
+     * prefilter (UGYANAZ, mint a hot-path `findActiveCandidates`/`loadCandidates`). **KRITIKUS:** `_deleted: null` (NEM
+     * `{$ne: true}`) — a `_deleted` DATE-mező; a mongoose a boolean `true`-t nem tudja Date-re castolni ("Cast to date
+     * failed") → a teljes cold-keresés elhalt (live-lelet 2026-06-24). A tag/kind nélkül a cold-supplement a query által
+     * EXPLICIT kiszűrt entry-ket is visszahozná.
+     */
+    static buildColdFilter(set) {
+        const filter = { dormant: true, embeddingStatus: 'completed', _deleted: null };
+        if (set.scopeIdSet.length) {
+            filter['scopePath.scopeId'] = { $in: set.scopeIdSet };
+        }
+        if (set.tagFilter && set.tagFilter.length) {
+            filter.tags = { $in: set.tagFilter };
+        }
+        if (set.kindFilter) {
+            filter.kind = set.kindFilter;
+        }
+        return filter;
+    }
+    /** Koszinusz-similarity két azonos-dimenziójú vektor között (0..1). */
+    static cosineSimilarity(a, b) {
+        let dot = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        if (!normA || !normB) {
+            return 0;
+        }
+        return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+    /** A `fam_memory` mongoose-modellje (a DS-példányosítás regisztrálja). */
+    memoryModel() {
+        new embedding_1.FAM_Entry_DataService({ dataParams: fam_memory_data_model_1.famMemory_dataParams, issuer: this.issuer });
+        return mongoose_1.default.models[fam_memory_data_model_1.famMemory_dataParams.dataName];
+    }
+}
+exports.FAM_MemoryColdSearch_ControlService = FAM_MemoryColdSearch_ControlService;