@futdevpro/fdp-agent-memory 1.1.30 → 1.1.113

package/build/src/_modules/mcp/_services/fam-capability-registry.service.js

@@ -310,6 +310,51 @@ class FAM_CapabilityRegistry_Service {
                 return this.ok(await this.getActiveRules(this.asScopeLayers(input.scopePath), input.includeContent !== false));
             },
         });
+        // detect_code_duplication (user-FR 2026-07-15 — fleet-duplikáció → bedrock-konszolidáció): a meglévő
+        // near-duplikátum motor (FAM_DuplicateScan_ControlService) CÉLZOTT, cross-project módban. A szűrők
+        // Mongo-prefilterként szűkítik a jelölt-halmazt (a 286k-s codebase táron is futtatható célzott scan),
+        // a `minProjects` (default 2) a cross-project clusterekre fókuszál. Read-only.
+        this.register({
+            name: 'detect_code_duplication', category: category,
+            description: 'CROSS-PROJECT kód-duplikáció FELDERÍTÉS (read-only; user-FR 2026-07-15): embedding-'
+                + 'similarity near-duplikátum clusterek egy tárban (default `codebase`), projekt-lefedettséggel '
+                + '(cluster → érintett projektek + fájlok + snippet) — a bedrock-konszolidáció döntés-előkészítője. '
+                + 'A szűrők (pathRegex/excludePathRegex/excludeRootRegex/projects/excludeProjects) Mongo-prefilterként '
+                + 'szűkítik a jelölt-halmazt MÉG a vektor-számítás előtt → a nagy táron CÉLZOTT scan-t futtass '
+                + '(pl. pathRegex egy fájl-mintára + excludeRootRegex a STALE/fork zajra). A `minProjects` (default 2) '
+                + 'csak a legalább ennyi KÜLÖNBÖZŐ projektet átfedő clustereket adja. A `capped` jelzi, ha a '
+                + 'jelölt-halmaz a `maxEntries`-nél nagyobb (emeld, vagy szűkíts tovább). A `threshold` default 0.93 '
+                + '(a drift-elt másolatok elkapásához lazább, mint a general 0.95).',
+            inputSchema: this.objectSchema({
+                table: this.tableSchema(false),
+                threshold: { type: 'number', description: 'Koszinusz-küszöb 0..1 (default 0.93).' },
+                neighbors: { type: 'number', description: 'Szomszéd-szám/entry (default 10).' },
+                maxEntries: { type: 'number', description: 'Jelölt-cap az O(n²) ellen (default 3000; a capped jelzi, ha több a jelölt).' },
+                maxClusters: { type: 'number', description: 'A visszaadott clusterek max száma (default 100).' },
+                pathRegex: { type: 'string', description: 'A sourceFilePath include-regexe (case-insensitive; pl. "\\\\.(ts|scss)$").' },
+                excludePathRegex: { type: 'string', description: 'A sourceFilePath exclude-regexe (pl. "\\\\.spec\\\\.ts$|node_modules").' },
+                excludeRootRegex: { type: 'string', description: 'A source.root exclude-regexe (pl. "STALE-projects").' },
+                projects: { type: 'array', items: { type: 'string' }, description: 'Csak ezek a projektek (scopePath project-layer canonicalName).' },
+                excludeProjects: { type: 'array', items: { type: 'string' }, description: 'Kizárt projektek (fork-zaj — pl. ccap — elnyomása).' },
+                minProjects: { type: 'number', description: 'Csak a legalább ennyi KÜLÖNBÖZŐ projektet átfedő clusterek (default 2).' },
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await embedding_1.FAM_DuplicateScan_ControlService.getInstance().scan({
+                    table: (this.optionalTable(input.table) ?? fam_table_type_enum_1.FAM_Table.codebase),
+                    threshold: this.asNumber(input.threshold) ?? 0.93,
+                    neighbors: this.asNumber(input.neighbors),
+                    maxEntries: this.asNumber(input.maxEntries),
+                    maxClusters: this.asNumber(input.maxClusters),
+                    pathRegex: this.asString(input.pathRegex),
+                    excludePathRegex: this.asString(input.excludePathRegex),
+                    excludeRootRegex: this.asString(input.excludeRootRegex),
+                    projects: this.asStringArray(input.projects),
+                    excludeProjects: this.asStringArray(input.excludeProjects),
+                    minProjects: this.asNumber(input.minProjects) ?? 2,
+                }));
+            },
+        });
     }
     /** maintenance → MP-2 (re-embed) + MP-3 (rebuild reference index). */
     registerMaintenance() {
@@ -433,6 +478,8 @@ class FAM_CapabilityRegistry_Service {
                 intoName: { type: 'string', description: 'A cél scope neve (scopeId helyett).' },
                 intoLayer: { type: 'string', description: 'Opcionális cél-layer az egyértelműsítéshez.' },
                 dryRun: { type: 'boolean', description: 'true (default): csak preview; false: ír.' },
+                force: { type: 'boolean', description: 'A cross-project merge-guard felülírása (KÜLÖNBÖZŐ projekt-gyökerek '
+                        + 'esetén is enged) — csak tudatos user-akcióra.' },
             }),
             handler: async (args) => {
                 const input = this.asObject(args);
@@ -440,6 +487,86 @@ class FAM_CapabilityRegistry_Service {
                     from: { scopeId: this.asString(input.fromScopeId), canonicalName: this.asString(input.fromName), layer: this.asString(input.fromLayer) },
                     into: { scopeId: this.asString(input.intoScopeId), canonicalName: this.asString(input.intoName), layer: this.asString(input.intoLayer) },
                     dryRun: input.dryRun !== false,
+                    force: input.force === true,
+                }));
+            },
+        });
+        this.register({
+            name: 'reset_scope', category: category,
+            description: 'Egy scope SCAN-eredetű entry-jeinek TÖRLÉSE (recovery egy félre-routolt scan után). A '
+                + '`sourceType` default `scan` → a manuális/agent/import-SZERZETT (pótolhatatlan) tartalmat SOHA nem '
+                + 'törli (csak az újra-szkennelhető scan-chunkokat). Opcionális `sourceRootContains`: a `source.root` '
+                + 'substring-szűrője a SEBÉSZI cross-root takarításhoz (pl. a `ccap-revisioned` gyökerű szennyezés a '
+                + '`ccap-client` scope-ból, a `ccap` saját entry-jeinek MEGTARTÁSÁVAL). **`dryRun:true` (DEFAULT) csak a '
+                + 'per-collection számot + a `rootSamples`-t adja (verifikáció: jó scope/gyökér?), NEM ír**; a tényleges '
+                + 'soft-delete (+ LVS-pool-kivétel) `dryRun:false`. A scope `scopeId`-val VAGY `canonicalName`(+`layer`)-rel.',
+            inputSchema: this.objectSchema({
+                scopeId: { type: 'string', description: 'A scope _id-ja (egyértelmű azonosítás).' },
+                canonicalName: { type: 'string', description: 'A scope neve (scopeId helyett).' },
+                layer: { type: 'string', description: 'Opcionális layer a canonicalName egyértelműsítéséhez.' },
+                sourceType: { type: 'string', description: 'A törlendő entry-k source.type-ja (default `scan`; a manuális/agent/import VÉDETT).' },
+                sourceRootContains: { type: 'string', description: 'Opcionális: csak az e substring-et tartalmazó `source.root`-ú entry-ket (sebészi cross-root takarítás).' },
+                table: this.tableSchema(false),
+                dryRun: { type: 'boolean', description: 'true (default): preview (szám + rootSamples); false: soft-delete + pool-kivétel.' },
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await scope_reference_1.FAM_ScopeMaintenance_ControlService.getInstance().resetScope({
+                    scopeId: this.asString(input.scopeId),
+                    canonicalName: this.asString(input.canonicalName),
+                    layer: this.asString(input.layer),
+                    sourceType: this.asString(input.sourceType),
+                    sourceRootContains: this.asString(input.sourceRootContains),
+                    table: this.asString(input.table),
+                    dryRun: input.dryRun !== false,
+                }));
+            },
+        });
+        this.register({
+            name: 'detect_scope_issues', category: category,
+            description: 'Scope-integritás SELF-CHECK (user-FR): felismeri az ÁRVA projekt-scope-okat (layer=project, de '
+                + 'nincs org-parent — tipikusan import-eredetű lapos scope) + a DUPLIKÁTUMOKAT (ugyanaz a name+layer '
+                + 'többször), entry-számmal. CSAK OLVAS (a takarítás a `merge_scopes`). A nagyobb/parented a javasolt `into`.',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok(await scope_reference_1.FAM_ScopeMaintenance_ControlService.getInstance().detectIssues()),
+        });
+        this.register({
+            name: 'suggest_scope_merges', category: category,
+            description: 'Scope-merge JAVASLATOK (user-FR — auto-felismerés AKCIONÁLHATÓVÁ): a `detect_scope_issues` '
+                + 'leleteiből KONKRÉT, futtatható `merge_scopes from→into` direktívák. A REPO-KULCS-csoportok elsőbbséget '
+                + 'élveznek (a KÜLÖNBÖZŐ nevű, AZONOS repo eseteket — pl. import-`10.3.3` vs scan-`ccap-revisioned` — is '
+                + 'elkapja, amit a puszta név-egyezés kihagy); az `into` a parented/legtöbb-entry-jű scope. CSAK OLVAS — '
+                + 'a tényleges összeolvasztáshoz futtasd a javasolt `merge_scopes` hívásokat.',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok(await scope_reference_1.FAM_ScopeMaintenance_ControlService.getInstance().suggestMerges()),
+        });
+        this.register({
+            name: 'set_global_rule', category: category,
+            description: 'GLOBÁLIS HARD-RULE jelölés (user-FR — a FAM fő feature-je): a megadott `rules`-bejegyzéseken '
+                + 'a `globalRule` flag BE-/KIkapcsolása. A `globalRule:true` rule-ok MINDEN scope-szűrt `rules`-lekérdezésbe '
+                + 'BEKERÜLNEK (scope-tól függetlenül) → a workspace-szintű hard-rules öröklődnek minden al-scope-ba. '
+                + 'Szelektor (legalább egy): `ids` (entry-_id-k) VAGY `scopeFilter` (egy scope subtree MINDEN rule-ja, '
+                + '`[{layer,rawName}]`) VAGY `tags`. `global` (default true) = jelölés / false = visszavonás. `dryRun` → csak szám.',
+            inputSchema: this.objectSchema({
+                ids: { type: 'array', items: { type: 'string' } },
+                scopeFilter: { type: 'array', items: this.objectSchema({ layer: { type: 'string' }, rawName: { type: 'string' } }) },
+                tags: { type: 'array', items: { type: 'string' } },
+                global: { type: 'boolean' },
+                dryRun: { type: 'boolean' },
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await retrieval_1.FAM_GlobalRule_ControlService.getInstance().setGlobalRule({
+                    ids: Array.isArray(input.ids) ? input.ids.map((value) => String(value)) : undefined,
+                    scopeFilter: Array.isArray(input.scopeFilter)
+                        ? input.scopeFilter.map((layer) => {
+                            const obj = this.asObject(layer);
+                            return { layer: this.asString(obj.layer), rawName: this.asString(obj.rawName) };
+                        })
+                        : undefined,
+                    tags: Array.isArray(input.tags) ? input.tags.map((value) => String(value)) : undefined,
+                    global: typeof input.global === 'boolean' ? input.global : undefined,
+                    dryRun: input.dryRun === true,
                 }));
             },
         });
@@ -465,16 +592,18 @@ class FAM_CapabilityRegistry_Service {
         this.register({
             name: 'deduplicate_entries', category: category,
             description: 'Duplikált entry-k AUDITja: contentHash-alapú dup-csoportok feltárása (a megtartandó + a '
-                + 'beolvasztható jelöltek). DRY-RUN MVP1: riportál, NEM ír. A tényleges összevonás (soft-delete) '
+                + 'beolvasztható jelöltek), a LEGNAGYOBB csoportok elöl (+ `totalGroups`/`truncated` — nincs néma '
+                + 'csonkolás). DRY-RUN MVP1: riportál, NEM ír. A tényleges összevonás (soft-delete) '
                 + 'BACKLOG — `dryRun:false` → clear BACKLOG-hiba (vak destruktív op TILOS).',
             inputSchema: this.objectSchema({
                 table: this.tableSchema(false),
+                maxGroups: { type: 'number', description: 'A visszaadott dup-csoportok max száma (default 500; a legnagyobbak elöl).' },
                 dryRun: { type: 'boolean', description: 'MVP1: mindig true (az összevonás BACKLOG). false → BACKLOG-hiba.' },
             }),
             handler: async (args) => {
                 const input = this.asObject(args);
                 this.assertDryRunOnly(input.dryRun, 'deduplicate_entries', 'duplikátum-összevonás (soft-delete)');
-                return this.ok(await this.deduplicateEntriesDryRun(this.optionalTable(input.table)));
+                return this.ok(await this.deduplicateEntriesDryRun(this.optionalTable(input.table), this.asNumber(input.maxGroups)));
             },
         });
     }
@@ -1021,7 +1150,8 @@ class FAM_CapabilityRegistry_Service {
                     .map((ref) => ref.scopeId)
                     .filter((scopeId) => scopeId && !activeScopeIds.has(scopeId));
                 if (missing.length && entry._id) {
-                    brokenLinks.push({ id: entry._id, table: target, missingScopeIds: missing });
+                    // String-koerció: a nyers Mongo-driver `_id`-je ObjectId (típus-konzisztencia a riportban).
+                    brokenLinks.push({ id: String(entry._id), table: target, missingScopeIds: missing });
                 }
             }
         }
@@ -1032,7 +1162,8 @@ class FAM_CapabilityRegistry_Service {
      * (legrégebbi `__created`) + a beolvasztható jelöltek. NEM ír — csak riportál (mit VONNA ÖSSZE). A
      * tényleges összevonás (soft-delete) BACKLOG.
      */
-    async deduplicateEntriesDryRun(table) {
+    async deduplicateEntriesDryRun(table, maxGroups) {
+        const groupCap = maxGroups ?? 500;
         const tables = table ? [table] : MAIN_TABLES;
         let scannedEntries = 0;
         const duplicateGroups = [];
@@ -1052,14 +1183,26 @@ class FAM_CapabilityRegistry_Service {
                 if (group.length < 2) {
                     continue;
                 }
-                // A megtartandó = a legrégebbi (`__created` ASC); a többi a merge-jelölt.
+                // A megtartandó = a legrégebbi (`__created` ASC); a többi a merge-jelölt. KRITIKUS: a nyers
+                // Mongo-driver `_id`-je ObjectId (NEM string) — String-koerció nélkül a `.length`-szűrő MINDEN
+                // merge-jelöltet kidobott (üres `mergeIds` — 2026-07-15 bugfix).
                 const sorted = group.slice().sort((a, b) => this.createdMs(a) - this.createdMs(b));
-                const keepId = sorted[0]._id ?? '';
-                const mergeIds = sorted.slice(1).map((entry) => entry._id ?? '').filter((id) => id.length > 0);
+                const keepId = String(sorted[0]._id ?? '');
+                const mergeIds = sorted.slice(1).map((entry) => String(entry._id ?? '')).filter((id) => id.length > 0);
                 duplicateGroups.push({ table: target, contentHash: contentHash, keepId: keepId, mergeIds: mergeIds });
             }
         }
-        return { dryRun: true, scannedEntries: scannedEntries, duplicateGroups: duplicateGroups };
+        // A LEGNAGYOBB csoportok elöl + output-cap (a full-tár audit 50k+ csoportot adhat — a riport a top-N-re
+        // fókuszál, a `totalGroups`/`truncated` jelzi a teljes terjedelmet; nincs néma csonkolás).
+        duplicateGroups.sort((left, right) => right.mergeIds.length - left.mergeIds.length);
+        const totalGroups = duplicateGroups.length;
+        return {
+            dryRun: true,
+            scannedEntries: scannedEntries,
+            totalGroups: totalGroups,
+            truncated: totalGroups > groupCap,
+            duplicateGroups: duplicateGroups.slice(0, groupCap),
+        };
     }
     // =========================================================================
     // MP-12 debug: explain-search / inspect-chunk / inspect-embedding

package/build/src/_modules/mcp/_services/fam-read-tool.service.js

@@ -7,6 +7,7 @@ const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
 const error_codes_const_1 = require("../../../_collections/error-codes.const");
 const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
 const retrieval_1 = require("../../retrieval");
 /**
  * `FAM_ReadTool_Service` (SP-6.2, dsgn-003 §2) — a `read` core-tool **transport-agnosztikus**
@@ -41,9 +42,78 @@ class FAM_ReadTool_Service {
         const request = this.toRetrievalRequest(input);
         const response = await retrieval_1.FAM_Retrieval_ControlService.getInstance().read(request);
         this.rebaseToBasePath(response, input.basePath);
+        // Token-budget ÉRVÉNYESÍTÉS (FAM-REV 2026-06-22): a read-válasz INLINE marad (különben a nagy találat-tartalom
+        // miatt a MCP-host FÁJLBA menti → extra olvasás-lépés). A `read.maxTokens` (default 4000) felett a hit-tartalom
+        // levágódik + a túlcsorduló hit-ek elhagyva, `truncated:true`-val. A FAM mindig DIREKT adja vissza a találatokat.
+        FAM_ReadTool_Service.applyTokenBudget(response, await FAM_ReadTool_Service.resolveMaxTokens());
         this.logReadActivity(input, response);
         return response;
     }
+    /** A `read.maxTokens` config feloldása (default/fallback 4000, min 256). */
+    static async resolveMaxTokens() {
+        try {
+            const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('read.maxTokens', {});
+            const value = typeof resolved.value === 'number' ? resolved.value : Number(resolved.value);
+            return Number.isFinite(value) && value >= 256 ? Math.floor(value) : 4000;
+        }
+        catch {
+            return 4000;
+        }
+    }
+    /**
+     * A read-válasz token-budgetre vágása (pure; ~4 char/token). A hit-eket sorrendben tartja meg; a budget elérésekor
+     * az aktuális hit `content`-jét a maradékra vágja (`…[levágva]`), a többi hitet elhagyja, és a query-eredményt
+     * `truncated:true`-ra állítja. Üres/`includeContent:false` válasz → no-op. Így a read INLINE marad (nem fájl).
+     *
+     * **ROUND-ROBIN allokáció (eval-lelet 2026-06-25 — multi-query starvation fix):** a budget KÖZÖS az egész válaszra,
+     * de NEM query-sorban fogy (különben az ELSŐ query elfogyasztaná, és a többi query 0 hitet kapna — silent data-loss
+     * a multi-query read-en). Helyette KÖRÖNKÉNT haladunk: minden körben MINDEN query EGY következő hitje kerül sorra
+     * (#1-ek, majd #2-k, …), így minden query megkapja a TOP-hitjeit, mielőtt a budget elfogy → egy query SEM éhezik.
+     */
+    static applyTokenBudget(response, maxTokens) {
+        const charBudget = Math.max(256, maxTokens) * 4;
+        const metaPerHit = 220; // a per-hit metaadat (score/path/heading/…) durva char-költsége
+        const results = response.results ?? [];
+        if (!results.length) {
+            return;
+        }
+        const kept = results.map(() => []);
+        const maxHits = Math.max(0, ...results.map((result) => (result.hits ?? []).length));
+        let used = 0;
+        let budgetExhausted = false;
+        for (let round = 0; round < maxHits && !budgetExhausted; round++) {
+            for (let ri = 0; ri < results.length && !budgetExhausted; ri++) {
+                const hit = (results[ri].hits ?? [])[round];
+                if (!hit) {
+                    continue;
+                }
+                if (used + metaPerHit >= charBudget) {
+                    budgetExhausted = true;
+                    break;
+                }
+                used += metaPerHit;
+                if (typeof hit.content === 'string' && hit.content.length > 0) {
+                    const remaining = charBudget - used;
+                    if (hit.content.length > remaining) {
+                        hit.content = `${hit.content.slice(0, Math.max(0, remaining - 12))}…[levágva]`;
+                        used = charBudget;
+                        kept[ri].push(hit);
+                        budgetExhausted = true;
+                        break;
+                    }
+                    used += hit.content.length;
+                }
+                kept[ri].push(hit);
+            }
+        }
+        // A megtartott hitek visszaírása + `truncated:true` ott, ahol elhagytunk hitet (a teljes halmaznál kevesebb maradt).
+        for (let ri = 0; ri < results.length; ri++) {
+            if ((results[ri].hits ?? []).length > kept[ri].length) {
+                results[ri].truncated = true;
+            }
+            results[ri].hits = kept[ri];
+        }
+    }
     /**
      * Ha a kérés `basePath`-et ad, a hit-ek `sourceFilePath`-ját a KANONIKUS `absolutePath`-ból a `basePath`-hez
      * RELATÍVAN írjuk át (a hívó saját workspace-kontextusa — FAM-REV-050), `/`-normalizálva. `absolutePath` nélküli

package/build/src/_modules/mcp/_services/fam-write-tool.service.js

@@ -6,6 +6,7 @@ const error_codes_const_1 = require("../../../_collections/error-codes.const");
 const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
 const fam_entry_data_model_1 = require("../../../_models/data-models/fam-entry.data-model");
 const embedding_1 = require("../../embedding");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
 const ingest_1 = require("../../ingest");
 const migration_1 = require("../../migration");
 const scope_reference_1 = require("../../scope-reference");
@@ -178,11 +179,44 @@ class FAM_WriteTool_Service {
         const warnings = embedOutcome.status === 'error'
             ? ['Az entry mentve, de az embedding sikertelen (érdemes ellenőrizni az embedding-providert; `re-embed`).']
             : [];
+        // NEAR-DUPLIKÁTUM-WARNING (user-FR 2026-06-25): a friss vektorral megnézzük, van-e a tárban „majdnem azonos"
+        // meglévő entry (koszinusz ≥ küszöb). Ha igen → jelzés (NEM blokkol) → az agent tudja: érdemes lehet a meglévőt
+        // UPDATE-elni, nem új entry-t létrehozni. A vektor már kész (nincs extra embed); a check 1 vektor-keresés.
+        if (embedOutcome.status === 'completed' && embedOutcome.vector.length) {
+            await this.appendDedupWarning(input.table, embedOutcome.vector, createdId, warnings);
+        }
         return this.baseOutput({
             operation: input.operation, table: input.table, scopePath: resolve.scopePath,
             uncertaintyNotes: resolve.uncertaintyNotes, created: createdId ? [createdId] : [], warnings: warnings,
         });
     }
+    /**
+     * Near-duplikátum-warning hozzáfűzése (user-FR 2026-06-25): a `write.dedupWarnEnabled`/`write.dedupWarnThreshold`
+     * config alapján a friss vektor legközelebbi szomszédait nézi; a küszöb fölötti meglévő entry(ke)t jelzi. Best-effort:
+     * a hiba NEM buktatja a write-ot (a jelzés kényelmi, nem kritikus).
+     */
+    async appendDedupWarning(table, vector, createdId, warnings) {
+        try {
+            const config = config_control_service_1.FAM_Config_ControlService.getInstance();
+            const enabledVal = (await config.resolve('write.dedupWarnEnabled', { table: table })).value;
+            if (enabledVal === false) {
+                return;
+            }
+            const thVal = (await config.resolve('write.dedupWarnThreshold', { table: table })).value;
+            const threshold = typeof thVal === 'number' ? thVal : 0.93;
+            const nearDups = await embedding_1.FAM_DedupWarn_ControlService.getInstance().check({
+                table: table, vector: vector, excludeId: createdId, threshold: threshold,
+            });
+            if (nearDups.length) {
+                const list = nearDups.map((dup) => `${dup.id} (${dup.score.toFixed(3)})`).join(', ');
+                warnings.push(`⚠ Near-duplikátum: az új tartalom nagyon hasonló a meglévő ${list} bejegyzés(ek)hez `
+                    + `(koszinusz ≥ ${threshold}). Fontold meg a MEGLÉVŐ frissítését (update) új entry létrehozása helyett.`);
+            }
+        }
+        catch {
+            // best-effort — a dedup-warning kényelmi, a hiba nem buktatja a write-ot.
+        }
+    }
     /**
      * `update` (dsgn-003 §3.1) → MP-1 modify + (ha content változott) MP-2 re-embed. A `target`
      * kötelező (`id`/`sourceFilePath`/`query`). A scope opcionális update-nél (a meglévő entry scope-ja
@@ -277,6 +311,8 @@ class FAM_WriteTool_Service {
             include: scan.include,
             exclude: scan.exclude,
             dryRun: scan.dryRun,
+            preserveHistory: scan.preserveHistory,
+            tableOverride: scan.tableOverride,
             weights: scan.weights,
             issuer: this.issuer,
         };

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;