@futdevpro/fdp-agent-memory 1.1.30 → 1.1.113

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;

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

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_MemoryDormancy_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 config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const embedding_1 = require("../../embedding");
+const fam_memory_data_model_1 = require("../../../_models/data-models/fam-memory.data-model");
+/**
+ * `FAM_MemoryDormancy_ControlService` (dsgn-013 §5, MAM F3) — a memória-DORMANCY sweep-je: a régóta-nem-felidézett,
+ * ritkán-használt `memory`-bejegyzéseket ALVÓ-vá (`dormant=true`) jelöli. Az alvó memória NEM hidratálódik a hot
+ * LVS-poolba (RAM-/boot-spórolás, dsgn-013 §5.2), de Mongo-oldali COLD kereséssel elérhető (§5.3) + megtaláláskor
+ * reaktiválódik (visszakerül a hot készletbe). **SOHA nem töröl** — a `dormant` csak hidratálás-kihagyás.
+ *
+ * **Mongo-kifejezhető szabály (== a pure `FAM_MemoryActivation_Util.isDormant` age+recall kapuja):** `lastRecalledAt`
+ * (hiányában `__created`) régebbi mint `minAgeDays`, ÉS `recallCount < maxRecallCount`. A sokszor-felidézett memória
+ * SOHA nem dormant. A sweep `updateMany` — nem érinti a vektor-poolt (a hatás a következő (re)hidratáláskor jön).
+ */
+class FAM_MemoryDormancy_ControlService {
+    static _instance;
+    issuer = 'FAM_MemoryDormancy_ControlService';
+    static MS_PER_DAY = 86_400_000;
+    static getInstance() {
+        if (!FAM_MemoryDormancy_ControlService._instance) {
+            FAM_MemoryDormancy_ControlService._instance = new FAM_MemoryDormancy_ControlService();
+        }
+        return FAM_MemoryDormancy_ControlService._instance;
+    }
+    /**
+     * A dormancy-sweep: a kvalifikáló `memory`-bejegyzések `dormant=true`-vá jelölése. Best-effort — a hiba logolódik és
+     * 0-val tér vissza (a boot-ot/működést nem buktatja). A `nowMs` injektálható (teszt-determinizmus). `dormancyEnabled
+     * = false` → no-op.
+     */
+    async sweep(nowMs) {
+        try {
+            const config = config_control_service_1.FAM_Config_ControlService.getInstance();
+            const enabledValue = (await config.resolve('memory.dormancyEnabled', {})).value;
+            if (enabledValue === false) {
+                return { enabled: false, markedDormant: 0 };
+            }
+            const minAgeDays = await this.resolveNumber(config, 'memory.dormantMinAgeDays', 180);
+            const maxRecallCount = await this.resolveNumber(config, 'memory.dormantMaxRecallCount', 2);
+            const model = this.memoryModel();
+            if (!model) {
+                return { enabled: true, markedDormant: 0 };
+            }
+            const filter = FAM_MemoryDormancy_ControlService.buildSweepFilter({
+                nowMs: nowMs, minAgeDays: minAgeDays, maxRecallCount: maxRecallCount,
+            });
+            const res = await model.updateMany(filter, { $set: { dormant: true } });
+            const marked = res.modifiedCount ?? 0;
+            if (marked > 0) {
+                fsm_dynamo_1.DyFM_Log.info(`[FAM memoryDormancy] ${marked} memória-bejegyzés ALVÓ-vá jelölve (age>${minAgeDays}d, recall<${maxRecallCount}).`);
+            }
+            return { enabled: true, markedDormant: marked };
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM memoryDormancy] sweep sikertelen (best-effort): ${error?.message}`);
+            return { enabled: true, markedDormant: 0 };
+        }
+    }
+    /**
+     * A sweep Mongo-filtere (PURE, tesztelhető): `completed` + még-nem-dormant + age-gát (`lastRecalledAt` VAGY a
+     * fallback `__created` a `minAgeDays`-cutoff előtt) + recall-gát (`recallCount < maxRecallCount`, a hiányzót is
+     * beleértve). A flag-csak frissítés → a vektor-poolt nem érinti.
+     */
+    static buildSweepFilter(set) {
+        const cutoffMs = set.nowMs - set.minAgeDays * FAM_MemoryDormancy_ControlService.MS_PER_DAY;
+        const cutoffDate = new Date(cutoffMs);
+        // age-gát: explicit lastRecalledAt a cutoff előtt, VAGY nincs lastRecalledAt és a __created a cutoff előtt.
+        const ageGate = {
+            $or: [
+                { lastRecalledAt: { $lt: cutoffMs } },
+                { lastRecalledAt: { $exists: false }, __created: { $lt: cutoffDate } },
+            ],
+        };
+        // recall-gát: recallCount < max (a hiányzó/0 is kvalifikál).
+        const recallGate = {
+            $or: [{ recallCount: { $lt: set.maxRecallCount } }, { recallCount: { $exists: false } }],
+        };
+        return {
+            embeddingStatus: 'completed',
+            dormant: { $ne: true },
+            $and: [ageGate, recallGate],
+        };
+    }
+    /** Egy szám-config feloldása a default-tal (a `resolve.value` lehet más típus → fallback). */
+    async resolveNumber(config, key, fallback) {
+        const value = (await config.resolve(key, {})).value;
+        return typeof value === 'number' ? value : fallback;
+    }
+    /** 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_MemoryDormancy_ControlService = FAM_MemoryDormancy_ControlService;

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_MemoryReactivation_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 fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const embedding_1 = require("../../embedding");
+const fam_memory_data_model_1 = require("../../../_models/data-models/fam-memory.data-model");
+/**
+ * `FAM_MemoryReactivation_ControlService` (dsgn-013 §4, MAM F2) — a memória FELIDÉZÉS-megerősítése. Amikor a `read`
+ * ténylegesen VISSZAAD egy `memory`-hitet (a felhasználó/agent felidézte), az „új energiát kap": `lastRecalledAt = now`,
+ * `recallCount += 1`, `dormant = false`. Ez az emberi memória retrieval-practice-e — a felidézett emlék megerősödik,
+ * feljebb rangsorol (a dsgn-013 §2 frequencyBoost + a friss recency), és ha alvó volt, visszakerül a hot készletbe.
+ *
+ * **Fire-and-forget:** a `read`-ből async, NEM blokkolja a választ; batch-elt `updateMany` (egy DB-hívás a top-K-ra).
+ * CSAK a ténylegesen visszaadott (használt) hitre fut → nincs „gyakran-keresett-de-irreleváns" felhízás. A hiba
+ * NÉMA-best-effort (a read már sikerült; a felidézés-frissítés elvesztése nem hiba). A flag NEM érinti a vektor-poolt.
+ */
+class FAM_MemoryReactivation_ControlService {
+    static _instance;
+    issuer = 'FAM_MemoryReactivation_ControlService';
+    static getInstance() {
+        if (!FAM_MemoryReactivation_ControlService._instance) {
+            FAM_MemoryReactivation_ControlService._instance = new FAM_MemoryReactivation_ControlService();
+        }
+        return FAM_MemoryReactivation_ControlService._instance;
+    }
+    /**
+     * A megadott `memory`-entry-k FELIDÉZÉS-frissítése (`updateMany`): `lastRecalledAt = nowMs`, `recallCount += 1`,
+     * `dormant = false`. Üres id-lista → no-op (0). Visszaadja a módosított darabszámot. **Nem dob** — a hiba logolódik
+     * és `0`-val tér vissza (best-effort, a read-et nem buktatja).
+     */
+    async reactivate(ids, nowMs) {
+        const uniqueIds = Array.from(new Set(ids.filter((id) => typeof id === 'string' && id.length)));
+        if (!uniqueIds.length) {
+            return 0;
+        }
+        try {
+            const model = this.memoryModel();
+            if (!model) {
+                return 0;
+            }
+            const res = await model.updateMany({ _id: { $in: uniqueIds } }, { $set: { lastRecalledAt: nowMs, dormant: false }, $inc: { recallCount: 1 } });
+            return res.modifiedCount ?? 0;
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM memoryReactivation] felidézés-frissítés sikertelen (best-effort): ${error?.message}`);
+            return 0;
+        }
+    }
+    /**
+     * A reaktiválandó `memory`-hit `_id`-k kiválasztása a read-eredmény hitjeiből (PURE, tesztelhető): CSAK a
+     * `memory`-táras, `_id`-vel bíró hitek, deduplikálva. A NEM-memory hitek (codebase/documents/…) kimaradnak.
+     */
+    static selectMemoryIds(hits) {
+        const ids = hits
+            .filter((hit) => hit.table === fam_table_type_enum_1.FAM_Table.memory && typeof hit.id === 'string' && hit.id.length > 0)
+            .map((hit) => hit.id);
+        return Array.from(new Set(ids));
+    }
+    /** 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_MemoryReactivation_ControlService = FAM_MemoryReactivation_ControlService;

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

@@ -117,8 +117,21 @@ class FAM_RetrievalCandidate_DataService {
         const filter = {};
         // ① scope-prefilter (subtree scopeId-halmaz). null → nincs scope-szűrés (teljes tár).
         if (input.scopeIdSet) {
-            // A scopePath denormalizált scope-ref tömb; a scopeId-ra szűrünk (dot-path a Mixed tömbön).
-            filter['scopePath.scopeId'] = { $in: input.scopeIdSet };
+            const isGlobalRulesTable = registryEntry.table === fam_table_type_enum_1.FAM_Table.rules && input.includeGlobalRules !== false;
+            if (isGlobalRulesTable) {
+                // GLOBÁLIS HARD-RULE öröklés (user-FR 2026-06-22 — a FAM fő feature-je): a scope-szűrt `rules`-lekérdezés
+                // a subtree-scope rule-jai MELLÉ a `globalRule:true` (workspace-szintű hard-rules) bejegyzéseket is
+                // behúzza — `(scope subtree-ben) VAGY (globális hard-rule)`. Így egy al-scope-ban is megkapjuk a
+                // mindenhol érvényes hard-rules-t. (A `$or` a tag/kind/isActive AND-feltételekkel kombinálódik.)
+                filter.$or = [
+                    { 'scopePath.scopeId': { $in: input.scopeIdSet } },
+                    { globalRule: true },
+                ];
+            }
+            else {
+                // A scopePath denormalizált scope-ref tömb; a scopeId-ra szűrünk (dot-path a Mixed tömbön).
+                filter['scopePath.scopeId'] = { $in: input.scopeIdSet };
+            }
         }
         // ② tag-prefilter (OR a tagek között): bármely tag-match bekerül.
         if (input.tagFilter && input.tagFilter.length) {