@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/migration/_services/fam-claude-mem-worker-reader.service.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ClaudeMemWorkerReader_Service = void 0;
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_claude_mem_source_type_enum_1 = require("../_enums/fam-claude-mem-source.type-enum");
+const fam_claude_mem_normalize_util_1 = require("../_collections/fam-claude-mem-normalize.util");
+/** A worker-api lekérdezés timeout-ja (ms) — fail-soft a worker-down ellen (NEM hang). */
+const WORKER_API_TIMEOUT_MS = 8000;
+/**
+ * `FAM_ClaudeMemWorkerReader_Service` (SP-11.1) — a **live worker-api reader** (`from=worker-api`,
+ * OPCIONÁLIS — csak ha a claude-mem worker fut). A worker REST-végpontjait (`GET /api/observations`,
+ * `GET /api/summaries`, `GET /api/prompts`, `GET /api/sessions`) olvassa Node 20 global `fetch`-csel
+ * (függőség-mentes), timeout-tal — worker-down → tiszta strukturált hiba (`FAM-IMP-SOURCE-001`), NEM
+ * hang. A reader UGYANAZT a normalizált halmazt adja, mint az export-JSON ugyanarra a tartalomra.
+ *
+ * **NEM az LLM-facing MCP-toolokon megy át** (search/timeline/get_observations — azok token-optimalizált
+ * lapozott eszközök): a worker-api bulk read-végpontjait használja közvetlenül (dsgn-009 §1).
+ */
+class FAM_ClaudeMemWorkerReader_Service {
+    static _instance;
+    /** Default issuer (a forrás-hibák issuer-éhez; dsgn-008). */
+    issuer = 'FAM_ClaudeMemWorkerReader_Service';
+    static getInstance() {
+        if (!FAM_ClaudeMemWorkerReader_Service._instance) {
+            FAM_ClaudeMemWorkerReader_Service._instance = new FAM_ClaudeMemWorkerReader_Service();
+        }
+        return FAM_ClaudeMemWorkerReader_Service._instance;
+    }
+    /**
+     * A worker-api 4 végpontjának olvasása + normalizálás (SP-11.1). A `baseUrl` a worker base-URL-je
+     * (pl. `http://localhost:3000`). A `prompts` lekérése CSAK `includePrompts:true` esetén (a default
+     * OFF — fölösleges hálózati kör elkerülése). Worker-down / nem-2xx / nem-JSON → `FAM-IMP-SOURCE-001`.
+     */
+    async read(set) {
+        if (!set.baseUrl || !set.baseUrl.trim().length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: 'A worker-api importhoz `path` (a worker base-URL) kötelező, pl. `http://localhost:3000`.',
+                issuer: this.issuer,
+                context: { operation: 'import-read-worker-api' },
+            });
+        }
+        const base = set.baseUrl.replace(/\/+$/, '');
+        const observations = await this.fetchArray(`${base}/api/observations`);
+        const summaries = await this.fetchArray(`${base}/api/summaries`);
+        const sessions = await this.fetchArray(`${base}/api/sessions`);
+        const prompts = set.includePrompts
+            ? await this.fetchArray(`${base}/api/prompts`)
+            : [];
+        return fam_claude_mem_normalize_util_1.FAM_ClaudeMemNormalize_Util.normalizeAll({
+            from: fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.workerApi,
+            observations: observations, summaries: summaries, prompts: prompts, sessions: sessions,
+            includePrompts: set.includePrompts,
+        });
+    }
+    /**
+     * Egy worker-végpont GET-je timeout-tal, a választ tömbre normalizálva. A worker `{ data: [...] }`
+     * vagy nyers `[...]` formát is adhat — mindkettőt kezeljük. Worker-down (abort/timeout) / nem-2xx /
+     * nem-JSON → `FAM-IMP-SOURCE-001` (deskriptív, NEM hang).
+     */
+    async fetchArray(url) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), WORKER_API_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, { method: 'GET', signal: controller.signal });
+            if (!response.ok) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                    message: `A claude-mem worker-api nem-2xx választ adott (HTTP ${response.status}): '${url}'. `
+                        + 'Fut a worker? (a worker-api út opcionális — használd a `export-json` forrást.)',
+                    issuer: this.issuer,
+                    context: { operation: 'import-read-worker-api' },
+                });
+            }
+            const parsed = await response.json();
+            return this.unwrapArray(parsed);
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'errorCode' in error) {
+                throw error;
+            }
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: `A claude-mem worker-api elérhetetlen (timeout/abort/hálózati hiba): '${url}'. `
+                    + 'A worker valószínűleg nem fut — használd a `export-json` (default) forrást.',
+                issuer: this.issuer,
+                context: { operation: 'import-read-worker-api' },
+                cause: error,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** A worker-válasz tömbre fejtése: nyers `[...]` VAGY `{ data: [...] }` VAGY `{ <kulcs>: [...] }`. */
+    unwrapArray(parsed) {
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+        if (parsed && typeof parsed === 'object') {
+            const container = parsed;
+            if (Array.isArray(container.data)) {
+                return container.data;
+            }
+            for (const value of Object.values(container)) {
+                if (Array.isArray(value)) {
+                    return value;
+                }
+            }
+        }
+        return [];
+    }
+}
+exports.FAM_ClaudeMemWorkerReader_Service = FAM_ClaudeMemWorkerReader_Service;

package/build/src/_modules/migration/_services/fam-import-dedup.data-service.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ImportDedup_DataService = void 0;
+const embedding_1 = require("../../embedding");
+const fam_target_mapping_util_1 = require("../_collections/fam-target-mapping.util");
+/**
+ * `FAM_ImportDedup_DataService` (SP-11.2, dsgn-009 §3) — a claude-mem import **idempotens 3-lépcsős
+ * dedup** lookup-ja. Statikus-szerű service (singleton); a `FAM_Entry_DataService`-en át kérdezi a
+ * cél-tárakat. **NEM tartunk élő DataService mezőt** (memory: dynts_dataservice_eager_resolve) —
+ * minden lookup előtt lazy `new FAM_Entry_DataService`.
+ *
+ * A 3 lépcső EGYMÁS UTÁN (dsgn-009 §3):
+ *   1. ELSŐDLEGES kulcs: `(importSource='claude-mem', importSourceId)` egyezés → SKIP-existing.
+ *   2. ha nincs id-egyezés: `contentHash` a cél-táron → egyezés → SKIP-duplicate-content.
+ *   3. ha még mindig nincs: KÜLÖN tartalom-ekvivalencia fallback — `sdk_session_id + title +
+ *      created_at_epoch` kompozit → egyezés → SKIP-duplicate-content. A kompozit NEM
+ *      `importSourceId`-alternatíva, csak ez a (3) lépcső.
+ *
+ * **BFR-AM-006 workaround:** a generic `DataService.compareData()` még nincs bedrock-szinten — ez a
+ * FAM-lokális helper. Kódolva úgy, hogy a bedrock `compareData()` landolásakor a lookup-belső
+ * cserélhető legyen, a `verdictFor` szerződés változatlanul.
+ */
+class FAM_ImportDedup_DataService {
+    static _instance;
+    /** A claude-mem import-forrás jelölője (a `importSource` mezőhöz; dsgn-009 §3). */
+    static IMPORT_SOURCE = 'claude-mem';
+    /** Default issuer a dedup-lookup-okhoz. */
+    issuer = 'FAM_ImportDedup_DataService';
+    static getInstance() {
+        if (!FAM_ImportDedup_DataService._instance) {
+            FAM_ImportDedup_DataService._instance = new FAM_ImportDedup_DataService();
+        }
+        return FAM_ImportDedup_DataService._instance;
+    }
+    /**
+     * A 3-lépcsős dedup-verdikt egy rekordra a cél-táron (dsgn-009 §3). A lépcsők EGYMÁS UTÁN
+     * értékelődnek; az első egyezés dönt. `import` → új (nincs egyezés); `skip-existing` → (1)
+     * importSourceId; `skip-duplicate-content` → (2) contentHash VAGY (3) fallback-kompozit.
+     */
+    async verdictFor(set) {
+        const dataService = this.dataServiceFor(set.table);
+        if (!dataService) {
+            // Nem-vektorizált / ismeretlen tár → nincs mivel dedup-olni: kezeljük új-ként (a mapping
+            // a 6 fő tár egyikére old fel, ez gyakorlatilag nem fordul elő — defenzív ág).
+            return 'import';
+        }
+        // (1) ELSŐDLEGES kulcs: importSource + importSourceId.
+        const byId = await dataService.findHydratableList({
+            importSource: FAM_ImportDedup_DataService.IMPORT_SOURCE,
+            importSourceId: set.importSourceId,
+        });
+        if (byId.length) {
+            return 'skip-existing';
+        }
+        // (2) contentHash a cél-táron (a claude-mem import-forrásra szűkítve a fals-pozitív ellen).
+        const byHash = await dataService.findHydratableList({
+            importSource: FAM_ImportDedup_DataService.IMPORT_SOURCE,
+            contentHash: set.contentHash,
+        });
+        if (byHash.length) {
+            return 'skip-duplicate-content';
+        }
+        // (3) KÜLÖN fallback: sdk_session_id + title + created_at_epoch kompozit (claude-mem natív
+        // observation-dedup). Csak akkor, ha mindhárom kulcs-tag jelen van (egyébként a kompozit
+        // megbízhatatlan — nincs fallback-egyezés, a rekord új).
+        if (this.hasCompositeKey(set.record)) {
+            const byComposite = await dataService.findHydratableList(this.compositeFilter(set.record));
+            if (byComposite.length) {
+                return 'skip-duplicate-content';
+            }
+        }
+        return 'import';
+    }
+    /** A (3) fallback kompozit-kulcs jelenléte: sdk_session_id + title + created_at_epoch mind kell. */
+    hasCompositeKey(record) {
+        return Boolean(record.sdkSessionId && record.title && typeof record.createdAtEpoch === 'number');
+    }
+    /**
+     * A (3) fallback content-ekvivalencia szűrő. A claude-mem natív `sdk_session_id + title +
+     * created_at_epoch` kompozit a FORRÁS-natív observation-dedup kulcsa — ugyanaz a session+cím+idő
+     * páros ugyanazt a tartalmat jelöli. A FAM-oldalon a tartalom-ekvivalenciát a TELJES vektorizált
+     * `content` exact-egyezésével érvényesítjük (a `composeContent` a title-lel KEZD, a join determinista),
+     * a claude-mem import-forrásra szűkítve. Így a kompozit-egyezés (azonos session-tartalom más row-id
+     * alatt) a content-azonosságon át kiderül — type-tiszta, `$regex` nélkül.
+     */
+    compositeFilter(record) {
+        const filter = {
+            importSource: FAM_ImportDedup_DataService.IMPORT_SOURCE,
+            content: fam_target_mapping_util_1.FAM_TargetMapping_Util.composeContent(record),
+        };
+        return filter;
+    }
+    /** Lazy `FAM_Entry_DataService` a tárhoz (a 6 fő tár); nem-vektorizált tár → undefined. */
+    dataServiceFor(table) {
+        const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(table);
+        if (!registryEntry) {
+            return undefined;
+        }
+        return new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+    }
+}
+exports.FAM_ImportDedup_DataService = FAM_ImportDedup_DataService;

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

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * `migration` modul barrel (MP-11, dsgn-009) — a claude-mem → FAM **egyirányú** migrációs engine
+ * publikus felülete. A fogyasztó-MP-k innen importálnak: a MP-6 `write.operation=import` thin-wrapper
+ * + a 5 import/migration capability (`preview_claude_mem_import` / `map_claude_mem_entries` /
+ * `import_claude_mem` / `run_import` / `rollback_import`), valamint a MP-9 `fam import claude-mem` CLI
+ * (downstream FOGYASZTÓ — vékony wrapper, NEM duplikál logikát).
+ *
+ * Boundary (dsgn-009 §7 HARD egyirányúság): NINCS reverse/export-adapter (FDP→claude-mem); az
+ * `importSource`/`importSourceId` csak provenance (audit/dedup). A SQLite-reader IZOLÁLT build-only
+ * függőség (BFR-AM-009 fallback) — a bedrock-reader landolásakor (MP-15) CSAK a reader-impl cserélődik.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ClaudeMemEntity_Type = exports.FAM_ClaudeMemSource_Type = exports.FAM_ImportContentHash_Util = exports.FAM_TargetMapping_Util = exports.FAM_ImportDedup_DataService = exports.FAM_ClaudeMemNormalize_Util = exports.FAM_ClaudeMemWorkerReader_Service = exports.FAM_ClaudeMemSqliteReader_Service = exports.FAM_ClaudeMemExportReader_Service = exports.FAM_ClaudeMemImport_ControlService = void 0;
+// SP-11.3 — a migrációs engine (preview → map → run → rollback)
+var fam_claude_mem_import_control_service_1 = require("./_services/fam-claude-mem-import.control-service");
+Object.defineProperty(exports, "FAM_ClaudeMemImport_ControlService", { enumerable: true, get: function () { return fam_claude_mem_import_control_service_1.FAM_ClaudeMemImport_ControlService; } });
+// SP-11.1 — forrás-readerek (export-JSON default / SQLite build-only / live worker-api)
+var fam_claude_mem_export_reader_service_1 = require("./_services/fam-claude-mem-export-reader.service");
+Object.defineProperty(exports, "FAM_ClaudeMemExportReader_Service", { enumerable: true, get: function () { return fam_claude_mem_export_reader_service_1.FAM_ClaudeMemExportReader_Service; } });
+var fam_claude_mem_sqlite_reader_service_1 = require("./_services/fam-claude-mem-sqlite-reader.service");
+Object.defineProperty(exports, "FAM_ClaudeMemSqliteReader_Service", { enumerable: true, get: function () { return fam_claude_mem_sqlite_reader_service_1.FAM_ClaudeMemSqliteReader_Service; } });
+var fam_claude_mem_worker_reader_service_1 = require("./_services/fam-claude-mem-worker-reader.service");
+Object.defineProperty(exports, "FAM_ClaudeMemWorkerReader_Service", { enumerable: true, get: function () { return fam_claude_mem_worker_reader_service_1.FAM_ClaudeMemWorkerReader_Service; } });
+var fam_claude_mem_normalize_util_1 = require("./_collections/fam-claude-mem-normalize.util");
+Object.defineProperty(exports, "FAM_ClaudeMemNormalize_Util", { enumerable: true, get: function () { return fam_claude_mem_normalize_util_1.FAM_ClaudeMemNormalize_Util; } });
+// SP-11.2 — dedup + target-mapping + content-hash
+var fam_import_dedup_data_service_1 = require("./_services/fam-import-dedup.data-service");
+Object.defineProperty(exports, "FAM_ImportDedup_DataService", { enumerable: true, get: function () { return fam_import_dedup_data_service_1.FAM_ImportDedup_DataService; } });
+var fam_target_mapping_util_1 = require("./_collections/fam-target-mapping.util");
+Object.defineProperty(exports, "FAM_TargetMapping_Util", { enumerable: true, get: function () { return fam_target_mapping_util_1.FAM_TargetMapping_Util; } });
+var fam_import_content_hash_util_1 = require("./_collections/fam-import-content-hash.util");
+Object.defineProperty(exports, "FAM_ImportContentHash_Util", { enumerable: true, get: function () { return fam_import_content_hash_util_1.FAM_ImportContentHash_Util; } });
+// enums + shared vokabulár (a MP-6 wiring + a CLI fogyasztja)
+var fam_claude_mem_source_type_enum_1 = require("./_enums/fam-claude-mem-source.type-enum");
+Object.defineProperty(exports, "FAM_ClaudeMemSource_Type", { enumerable: true, get: function () { return fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type; } });
+var fam_claude_mem_interface_1 = require("./_models/interfaces/fam-claude-mem.interface");
+Object.defineProperty(exports, "FAM_ClaudeMemEntity_Type", { enumerable: true, get: function () { return fam_claude_mem_interface_1.FAM_ClaudeMemEntity_Type; } });

package/build/src/_modules/retrieval/_models/interfaces/fam-retrieval.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RetrievalCandidate_DataService = void 0;
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const embedding_1 = require("../../embedding");
+/**
+ * `FAM_RetrievalCandidate_DataService` (SP-5.1) — a read-pipeline ① scope + ② tag/kind **Mongo-szintű
+ * prefilter**-e: a vektor-keresés ELŐTT (dsgn-005 §2.1/§2.2) szűkíti a jelölt-halmazt egy tárra.
+ *
+ * A `FAM_Entry_DataService`-t (MP-2) használja a per-tár `dataParams`-szal (a registry-ből), így a 6
+ * fő tár mindegyikére a közös `FAM_Entry` bázis-mezőkre szűr. A `findDataList` (a `DyNTS_DataService`
+ * alap-query-je) az aktív (nem soft-delete-elt) rekordokat adja — a `_deleted` guard így beépített.
+ * A `rules.isActive:false` szabály (dsgn-001 §4) explicit kizárásra kerül (a `findDataList` filterén).
+ *
+ * **A prefilter bizonyíthatóan a vektor-keresés ELŐTT szűkít (acceptance dsgn-005 §9.3):** a candidate-ID
+ * halmazt adja a `FAM_VectorSearch_ControlService.search({ candidateIds })`-nek (prefilter→vektor,
+ * dsgn-006 §4.3), így a koszinusz csak a szűkített halmazon fut.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** NEM tartunk élő DataService mezőt; minden
+ * művelet előtt lazy `new FAM_Entry_DataService`.
+ */
+class FAM_RetrievalCandidate_DataService {
+    issuer = 'FAM_RetrievalCandidate_DataService';
+    /**
+     * A prefilter-feltételeknek megfelelő jelölt-entry-k egy tárból (dsgn-005 §2.1/§2.2). A
+     * `findDataList` az AKTÍV (nem-`_deleted`) rekordokat adja; a `rules` táron az `isActive:true`
+     * szűrés is rákerül. A scope subtree (`scopePath.scopeId $in scopeIdSet`), a tag (OR, `tags $in`)
+     * és a kind a Mongo-filterben. Nem-vektorizált / ismeretlen tár → üres lista (a registry dönt).
+     */
+    async loadCandidates(input) {
+        const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(input.table);
+        if (!registryEntry) {
+            return [];
+        }
+        const filter = this.buildFilter(input, registryEntry);
+        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        return dataService.findDataList(filter);
+    }
+    /**
+     * A Mongo-prefilter összeállítása (dsgn-005 §2.1/§2.2). A `scopePath.scopeId $in scopeIdSet`
+     * subtree-szemantika (a `scopeIdSet` MÁR a subtree-uniót tartalmazza, MP-3 `expandForRead`); a
+     * `tags $in tagFilter` OR-szemantika; a `kind` egyezés; a `rules` táron `isActive:true`. A
+     * `_deleted`-kizárás a `findDataList` alap-konvenciójában (aktív-only) van.
+     */
+    buildFilter(input, registryEntry) {
+        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 };
+        }
+        // ② tag-prefilter (OR a tagek között): bármely tag-match bekerül.
+        if (input.tagFilter && input.tagFilter.length) {
+            filter.tags = { $in: input.tagFilter };
+        }
+        // ② kind-prefilter (egyetlen kind).
+        if (input.kindFilter) {
+            filter.kind = input.kindFilter;
+        }
+        // Soft-delete/aktív guard a `rules` táron (dsgn-001 §4): inaktív szabály SOHA nem jelölt.
+        if (registryEntry.table === fam_table_type_enum_1.FAM_Table.rules) {
+            filter.isActive = true;
+        }
+        return filter;
+    }
+}
+exports.FAM_RetrievalCandidate_DataService = FAM_RetrievalCandidate_DataService;

package/build/src/_modules/retrieval/_services/fam-retrieval-suggestions.util.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RetrievalSuggestions_Util = void 0;
+/** A scope-javaslat domináns-küszöbe (>50% a relevantSet-ben; dsgn-005 §4.4). */
+const SCOPE_DOMINANCE_RATIO = 0.5;
+/** A tag-javaslat előfordulási küszöbe (>40% a relevantSet-ben; dsgn-005 §4.4). */
+const TAG_FREQUENCY_RATIO = 0.4;
+/**
+ * `FAM_RetrievalSuggestions_Util` (SP-5.3, dsgn-005 §4.4) — a **konkrét, gépelhető** szűkítési
+ * javaslatok generátora a `relevantSet` valós statisztikáiból + a query tényleges paramétereiből.
+ * Statikus util (nincs függőség). A javaslatok rendezettek: scope → tag → minScore → topK → kind.
+ *
+ * Üres `relevantSet` → üres javaslat-lista (dsgn-005 §4.4 vége). Minden javaslat-típus külön
+ * feltételhez kötött (graceful: a hiányzó statisztikájú javaslat KIMARAD, nem hiba — dsgn-005 §kockázat).
+ */
+class FAM_RetrievalSuggestions_Util {
+    /**
+     * A teljes, rendezett javaslat-lista (dsgn-005 §4.4). A sorrend kötött (scope → tag → minScore →
+     * topK → kind). Üres relevantSet → `[]`. A scope/tag/kind a relevantSet eloszlásából; a minScore a
+     * returnedHits-határ és az első levágott elem közti érték; a topK a teljes releváns halmazhoz.
+     */
+    static generate(input) {
+        if (!input.relevantSet.length) {
+            return [];
+        }
+        const suggestions = [];
+        const scopeSuggestion = FAM_RetrievalSuggestions_Util.scopeSuggestion(input);
+        if (scopeSuggestion) {
+            suggestions.push(scopeSuggestion);
+        }
+        const tagSuggestion = FAM_RetrievalSuggestions_Util.tagSuggestion(input);
+        if (tagSuggestion) {
+            suggestions.push(tagSuggestion);
+        }
+        const minScoreSuggestion = FAM_RetrievalSuggestions_Util.minScoreSuggestion(input);
+        if (minScoreSuggestion) {
+            suggestions.push(minScoreSuggestion);
+        }
+        const topKSuggestion = FAM_RetrievalSuggestions_Util.topKSuggestion(input);
+        if (topKSuggestion) {
+            suggestions.push(topKSuggestion);
+        }
+        const kindSuggestion = FAM_RetrievalSuggestions_Util.kindSuggestion(input);
+        if (kindSuggestion) {
+            suggestions.push(kindSuggestion);
+        }
+        return suggestions;
+    }
+    /**
+     * Scope-javaslat (dsgn-005 §4.4 #1): csak ha a query NEM adott scope-filtert ÉS a relevantSet-ben
+     * van domináns mélyebb (a legmélyebb layer) scope-entitás (>50%). A javaslat a domináns scope
+     * canonical nevét + layerét + arányt írja ki.
+     */
+    static scopeSuggestion(input) {
+        // Csak ha a query nem adott scope-filtert (a már-szűkítettet nem javasoljuk újra).
+        if (input.query.scopeFilter && input.query.scopeFilter.length) {
+            return undefined;
+        }
+        // A legmélyebb layer scope-entitás-eloszlása a relevantSet hit-jeiben (a leaf a legspecifikusabb).
+        const countByScope = new Map();
+        for (const hit of input.relevantSet) {
+            if (!hit.scopePath.length) {
+                continue;
+            }
+            const leaf = hit.scopePath[hit.scopePath.length - 1];
+            const key = leaf.scopeId;
+            const existing = countByScope.get(key);
+            if (existing) {
+                existing.count++;
+            }
+            else {
+                countByScope.set(key, { layer: leaf.layer, canonicalName: leaf.canonicalName, count: 1 });
+            }
+        }
+        let dominant = undefined;
+        for (const entry of countByScope.values()) {
+            if (!dominant || entry.count > dominant.count) {
+                dominant = entry;
+            }
+        }
+        if (!dominant) {
+            return undefined;
+        }
+        const ratio = dominant.count / input.relevantSet.length;
+        if (ratio <= SCOPE_DOMINANCE_RATIO) {
+            return undefined;
+        }
+        const percent = Math.round(ratio * 100);
+        return `szűkíts scope-ra: ${dominant.layer}=${dominant.canonicalName} (a találatok ${percent}%-a ehhez tartozik)`;
+    }
+    /**
+     * Tag-javaslat (dsgn-005 §4.4 #2): a relevantSet leggyakoribb, a `tagFilter`-ben még nem szereplő
+     * tagje (>40% előfordulás). A már aktív tag-filtereket kizárjuk.
+     */
+    static tagSuggestion(input) {
+        const activeTags = new Set(input.query.tagFilter ?? []);
+        const countByTag = new Map();
+        for (const hit of input.relevantSet) {
+            for (const tag of hit.tags) {
+                if (activeTags.has(tag)) {
+                    continue;
+                }
+                countByTag.set(tag, (countByTag.get(tag) ?? 0) + 1);
+            }
+        }
+        let bestTag = undefined;
+        let bestCount = 0;
+        for (const [tag, count] of countByTag.entries()) {
+            if (count > bestCount) {
+                bestTag = tag;
+                bestCount = count;
+            }
+        }
+        if (!bestTag) {
+            return undefined;
+        }
+        const ratio = bestCount / input.relevantSet.length;
+        if (ratio <= TAG_FREQUENCY_RATIO) {
+            return undefined;
+        }
+        const percent = Math.round(ratio * 100);
+        return `adj tagFilter-t: ['${bestTag}'] (a releváns találatok ${percent}%-án jelen van)`;
+    }
+    /**
+     * minScore-javaslat (dsgn-005 §4.4 #3): a returnedHits utolsó eleme és a (topK+1.) levágott elem
+     * `finalScore`-jának számtani közepe (2 tizedes) + a becsült megmaradó találat-szám. Csak akkor,
+     * ha van levágott elem (topK+1 létezik).
+     */
+    static minScoreSuggestion(input) {
+        if (input.relevantSet.length <= input.effectiveTopK) {
+            return undefined;
+        }
+        const lastReturned = input.relevantSet[input.effectiveTopK - 1];
+        const firstCut = input.relevantSet[input.effectiveTopK];
+        const suggested = Math.round(((lastReturned.finalScore + firstCut.finalScore) / 2) * 100) / 100;
+        // A becsült megmaradó: hány relevantSet-elem finalScore-ja >= a javasolt küszöb.
+        const remaining = input.relevantSet.filter((hit) => hit.finalScore >= suggested).length;
+        const current = input.query.minScore ?? 0;
+        return `emeld a minScore-t ${suggested.toFixed(2)}-re (jelenleg ${current}; ez ~${remaining} találatra szűkít)`;
+    }
+    /**
+     * topK-javaslat (dsgn-005 §4.4 #4): csak `truncated:true`-nál; javasolt érték
+     * `min(totalRelevant, MAX_PAGE_SIZE)`, a teljes releváns halmazért.
+     */
+    static topKSuggestion(input) {
+        if (!input.truncated) {
+            return undefined;
+        }
+        const totalRelevant = input.relevantSet.length;
+        const suggested = Math.min(totalRelevant, input.maxPageSize);
+        return `emeld a topK-t ${suggested}-re a teljes releváns halmazért (totalRelevant=${totalRelevant})`;
+    }
+    /**
+     * kindFilter-javaslat (dsgn-005 §4.4 #5): csak ha a relevantSet ≥2 különböző `kind`-ot tartalmaz
+     * ÉS nincs aktív `kindFilter`. A javaslat a leggyakoribb kind-ot ajánlja.
+     */
+    static kindSuggestion(input) {
+        if (input.query.kindFilter) {
+            return undefined;
+        }
+        const countByKind = new Map();
+        for (const hit of input.relevantSet) {
+            if (!hit.kind) {
+                continue;
+            }
+            countByKind.set(hit.kind, (countByKind.get(hit.kind) ?? 0) + 1);
+        }
+        if (countByKind.size < 2) {
+            return undefined;
+        }
+        let bestKind = undefined;
+        let bestCount = 0;
+        for (const [kind, count] of countByKind.entries()) {
+            if (count > bestCount) {
+                bestKind = kind;
+                bestCount = count;
+            }
+        }
+        return `adj kindFilter-t: '${bestKind}' (a releváns találatok kindjai vegyesek)`;
+    }
+}
+exports.FAM_RetrievalSuggestions_Util = FAM_RetrievalSuggestions_Util;