@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/embedding/_services/fam-vector-search.control-service.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_VectorSearch_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const local_vector_search_1 = require("@futdevpro/nts-dynamo/local-vector-search");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_store_registry_const_1 = require("../_collections/fam-store-registry.const");
+const fam_embedding_control_service_1 = require("./fam-embedding.control-service");
+const fam_entry_data_service_1 = require("./fam-entry.data-service");
+/**
+ * `FAM_VectorSearch_ControlService` (SP-2.2, dsgn-006 §4) — **Memory Vector Search** (BFR-AM-001
+ * workaround). Singleton. A vektorok a SAJÁT MongoDB-ben élnek (`FAM_Entry.contentVector`); boot-kor
+ * a Dynamo `LVS_VectorPool_ControlService` **in-memory** pool-jába hidratálódnak (tár-particionált).
+ * A `read` (MP-5) ezen a pool-on futtat koszinusz-keresést. **NEM** MongoDB Atlas Vector Search.
+ *
+ * **Pool-választás:** a magas-szintű `DyNTS_LVS_VectorDataService` minden `vectorSearch`-nél a DB-ből
+ * újraépítené a pool-t + string-input-ot vektorizálna (OpenAI). A FAM ehelyett közvetlenül a
+ * `LVS_VectorPool_ControlService`-t (a Dynamo LVS in-memory engine-je) használja per-tár, perzisztens
+ * Mongo-hidratálással — így VALÓDI per-hit koszinusz-score-t ad (BFR-AM-007) és a query-vektort a
+ * provider-agnosztikus `FAM_Embedding_ControlService` adja (NEM hardwired OpenAI).
+ *
+ * **Dimenzió-konzisztencia (acceptance #6):** egy tár pool-ja nem kever eltérő dimenziójú vektort —
+ * a hidratálás csak a `dims`-egyező completed entry-ket veszi fel (a dimenzió-váltás re-embedet igényel).
+ */
+class FAM_VectorSearch_ControlService {
+    static _instance;
+    issuer = 'FAM_VectorSearch_ControlService';
+    /** Tár-particionált in-memory pool-ok (a Dynamo LVS engine-jén; BFR-AM-001). */
+    pools = new Map();
+    /** A pool dimenziója táranként (homogenitás-ellenőrzés; null = még üres pool). */
+    poolDims = new Map();
+    /** Hidratált-e már az adott tár pool-ja (a `search` bootstrap-skip jelzéséhez). */
+    hydrated = new Map();
+    static getInstance() {
+        if (!FAM_VectorSearch_ControlService._instance) {
+            FAM_VectorSearch_ControlService._instance = new FAM_VectorSearch_ControlService();
+        }
+        return FAM_VectorSearch_ControlService._instance;
+    }
+    // =========================================================================
+    // BOOT-HIDRATÁLÁS (dsgn-006 §4.1)
+    // =========================================================================
+    /**
+     * A teljes vektor-pool hidratálása minden fő tárra (dsgn-006 §4.1). Szerver-boot-kor hívandó (a
+     * bootstrap köti be). Tár-particionált: minden tárra külön pool. A `completed && !_deleted` entry-k
+     * `contentVector`-jét tölti be (`key = entry._id`). Hiba esetén `FAM-VEC-HYDRATE-001` (nem néma),
+     * de a többi tár hidratálása FOLYTATÓDIK (egy tár bukása nem dönti le az egészet).
+     */
+    async hydrateAll() {
+        for (const entry of fam_store_registry_const_1.FAM_STORE_REGISTRY) {
+            try {
+                await this.hydrateTable(entry.table);
+            }
+            catch (error) {
+                // No-silent-failure: a hidratálás-hiba persistált (a global handler kapja), de a többi
+                // tár hidratálása folytatódik (a `hydrateTable` dob, itt logoljuk + tovább).
+                fsm_dynamo_1.DyFM_Log.warn(`[FAM hydrate] '${entry.table}' tár hidratálása sikertelen: ${error?.message}`);
+            }
+        }
+    }
+    /**
+     * Egy tár pool-jának hidratálása (dsgn-006 §4.1). A `completed`-státuszú, nem-üres-vektorú entry-ket
+     * tölti be; az `error`-státuszúak KIMARADNAK (nincs használható vektor — acceptance, dsgn-006 §3.1).
+     * A pool dimenzióját az első felvett vektor rögzíti; eltérő dimenziójú vektor → kihagyva + warn.
+     */
+    async hydrateTable(table) {
+        const registryEntry = fam_store_registry_const_1.FAM_StoreRegistry_Util.getEntry(table);
+        if (!registryEntry) {
+            return;
+        }
+        const pool = this.getOrCreatePool(table);
+        pool.clearPool();
+        this.poolDims.set(table, null);
+        const dataService = new fam_entry_data_service_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const filter = { embeddingStatus: 'completed' };
+        let entries;
+        try {
+            entries = await dataService.findHydratableList(filter);
+        }
+        catch (error) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.vecHydrate,
+                message: `A(z) '${table}' tár vektor-hidratálása sikertelen a Mongo-olvasásnál.`,
+                issuer: this.issuer,
+                cause: error,
+                context: { operation: 'hydrate', table: table },
+            });
+        }
+        let loaded = 0;
+        for (const entry of entries) {
+            if (!entry._id || !entry.contentVector?.length) {
+                continue;
+            }
+            if (this.acceptVectorForPool(table, entry.contentVector)) {
+                pool.addVector(entry._id, entry.contentVector);
+                loaded++;
+            }
+        }
+        this.hydrated.set(table, true);
+        fsm_dynamo_1.DyFM_Log.log(`[FAM hydrate] '${table}' tár: ${loaded} vektor betöltve az in-memory pool-ba.`);
+    }
+    // =========================================================================
+    // PERSIST-ON-WRITE upsert (dsgn-006 §3) — a write/scan path hívja mentés után
+    // =========================================================================
+    /**
+     * Egy entry vektorának pool-ba illesztése mentés UTÁN (dsgn-006 §3). A persistence (Mongo
+     * `contentVector`) a write-path felelőssége; ITT a már-persistált vektor az in-memory pool-ba kerül
+     * (`addVector` = upsert; a pool felülírja a meglévőt azonos kulcson). Dimenzió-eltérés → kihagyva + warn.
+     */
+    upsertVector(set) {
+        if (!set.vector.length) {
+            return;
+        }
+        const pool = this.getOrCreatePool(set.table);
+        if (this.acceptVectorForPool(set.table, set.vector)) {
+            pool.addVector(set.id, set.vector);
+        }
+    }
+    /** Egy entry vektorának eltávolítása a pool-ból (soft-delete / error-státusz után). */
+    removeVector(table, id) {
+        this.getOrCreatePool(table).removeVector(id);
+    }
+    // =========================================================================
+    // SEARCH (dsgn-006 §4.2/4.3) — koszinusz a (szűkített) pool-on
+    // =========================================================================
+    /**
+     * Vektor-keresés egy tár pool-jában (dsgn-006 §4.2). MVP1: `cosineSimilarity` (l2-normalizált
+     * vektorokon). A `queryVector` VAGY a `queryText` (ez esetben a provider-agnosztikus
+     * `FAM_Embedding_ControlService` embeddeli a `table`-re feloldva). A `candidateIds` (prefilter→vektor,
+     * dsgn-006 §4.3) szűkíti a jelölt-halmazt MIELŐTT a koszinusz fut — kisebb számítás. A score VALÓDI
+     * koszinusz (BFR-AM-007). Üres pool / hiányzó embedding → `FAM-VEC-SEARCH-001` (bootstrap-skip jelzés).
+     */
+    async search(input) {
+        const queryVector = await this.resolveQueryVector(input);
+        if (!queryVector.length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.vecSearch,
+                message: `Üres query-vektor a(z) '${input.table}' tár keresésénél `
+                    + `(sem queryVector, sem embeddelhető queryText).`,
+                issuer: this.issuer,
+                context: { operation: 'search', table: input.table, query: input.queryText },
+            });
+        }
+        const pool = this.getOrCreatePool(input.table);
+        const poolSize = pool.getAll().size;
+        if (!poolSize) {
+            // Bootstrap-skip jelzés (dsgn-006 §4.1): üres pool (embedding nincs konfigurálva / nincs
+            // completed entry). NEM néma — a capability + UI piros banner ezt jelzi (dsgn-008/dsgn-011).
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.vecSearch,
+                message: `A(z) '${input.table}' tár vektor-pool-ja ÜRES (bootstrap-skip): nincs hidratált, `
+                    + `completed-embeddingű vektor. Ellenőrizd az embedding-konfigurációt (test_embedding_provider).`,
+                issuer: this.issuer,
+                context: { operation: 'search', table: input.table },
+            });
+        }
+        // Prefilter→vektor (dsgn-006 §4.3): ha van candidate-szűkítés, a koszinusz CSAK a szűkített
+        // halmazon fut (a teljes pool helyett egy ideiglenes szűkített pool-on) — kisebb számítás.
+        if (input.candidateIds && input.candidateIds.length) {
+            return this.searchInCandidates(pool, queryVector, input.candidateIds, input.topK);
+        }
+        // A Dynamo LVS pool `search` per-hit VALÓDI score-t ad (cosine; BFR-AM-007 a maga-számolt score).
+        const results = pool.search(queryVector, input.topK, local_vector_search_1.LVS_Search_Mode.cosineSimilarity);
+        return results.map((hit) => ({ id: hit.id, score: hit.score }));
+    }
+    /** Egy tár pool-jának mérete (a `test_vector_search` / `get_storage_usage` capability — dsgn-003). */
+    getPoolSize(table) {
+        return this.getOrCreatePool(table).getAll().size;
+    }
+    /** Hidratált-e már egy tár (a bootstrap-skip diagnosztikához). */
+    isHydrated(table) {
+        return this.hydrated.get(table) ?? false;
+    }
+    // =========================================================================
+    // helpers
+    // =========================================================================
+    /**
+     * A koszinusz egy SZŰKÍTETT jelölt-halmazon (prefilter→vektor, dsgn-006 §4.3). Egy ideiglenes
+     * pool-ba másoljuk a candidate-ID-k vektorait, és azon futtatjuk a koszinuszt — így a számítás a
+     * szűkített halmazra korlátozódik (a jelöltszám bizonyíthatóan kisebb a teljes tárnál — acceptance #4).
+     */
+    searchInCandidates(pool, queryVector, candidateIds, topK) {
+        const all = pool.getAll();
+        const scoped = new local_vector_search_1.LVS_VectorPool_ControlService();
+        let scopedCount = 0;
+        for (const id of candidateIds) {
+            const vector = all.get(id);
+            if (vector) {
+                scoped.addVector(id, vector);
+                scopedCount++;
+            }
+        }
+        if (!scopedCount) {
+            return [];
+        }
+        const results = scoped.search(queryVector, topK, local_vector_search_1.LVS_Search_Mode.cosineSimilarity);
+        return results.map((hit) => ({ id: hit.id, score: hit.score }));
+    }
+    /** A query-vektor feloldása: kész `queryVector`, vagy a `queryText` embeddelése (provider-agnosztikus). */
+    async resolveQueryVector(input) {
+        if (input.queryVector && input.queryVector.length) {
+            return input.queryVector;
+        }
+        if (input.queryText && input.queryText.trim().length) {
+            return fam_embedding_control_service_1.FAM_Embedding_ControlService.getInstance().embedOne({
+                text: input.queryText,
+                table: input.table,
+                callType: 'embed-query',
+                issuer: this.issuer,
+            });
+        }
+        return [];
+    }
+    /** A tár pool-ja (lazy létrehozás). */
+    getOrCreatePool(table) {
+        let pool = this.pools.get(table);
+        if (!pool) {
+            pool = new local_vector_search_1.LVS_VectorPool_ControlService();
+            this.pools.set(table, pool);
+            this.poolDims.set(table, null);
+        }
+        return pool;
+    }
+    /**
+     * Dimenzió-homogenitás kapu (dsgn-006 §6.2 / acceptance #6): a pool első vektora rögzíti a
+     * dimenziót; az ettől eltérő dimenziójú vektort NEM vesszük fel (nem kever eltérő dimenziót egy
+     * tár pool-jában — a dimenzió-váltás explicit re-embedet igényel). Eltérés → warn (nem néma).
+     */
+    acceptVectorForPool(table, vector) {
+        const current = this.poolDims.get(table);
+        if (current === null || current === undefined) {
+            this.poolDims.set(table, vector.length);
+            return true;
+        }
+        if (current !== vector.length) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM vector-pool] '${table}' tár dimenzió-eltérés: pool=${current}, vektor=${vector.length} `
+                + `→ kihagyva (re-embed szükséges; dsgn-006 §6.2).`);
+            return false;
+        }
+        return true;
+    }
+}
+exports.FAM_VectorSearch_ControlService = FAM_VectorSearch_ControlService;

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

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * `embedding` modul barrel (MP-2, dsgn-006) — az embedding + Memory Vector Search engine publikus
+ * felülete. A fogyasztó-MP-k (MP-4 scan/auto-embed, MP-5 read/retrieval, MP-6 capabilities) innen
+ * importálnak. A bootstrap (`App.postProcess`) a `FAM_EmbeddingBootstrap_ControlService`-t hívja.
+ *
+ * Boundary (dsgn-006 §1): a provider-impl-ek (LM Studio HTTP / mock) projekt-lokális workaround-ok
+ * (BFR-AM-002/008); a bedrock-csere (MP-15) a `FAM_EmbeddingProvider` interfész mögött non-breaking.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_EmbeddingBootstrap_ControlService = exports.FAM_EmbeddingCost_ControlService = exports.FAM_EmbeddingPipeline_ControlService = exports.FAM_EmbeddingPreset_ControlService = exports.FAM_StoreRegistry_Util = exports.FAM_STORE_REGISTRY = exports.FAM_Entry_DataService = exports.FAM_VectorSearch_ControlService = exports.FAM_MOCK_EMBEDDING_DIMS = exports.FAM_Mock_EmbeddingProvider = exports.FAM_LMStudio_EmbeddingProvider = exports.FAM_OpenAI_EmbeddingProvider = exports.FAM_Embedding_ControlService = void 0;
+// SP-2.1 — provider-dispatch kapu + providerek
+var fam_embedding_control_service_1 = require("./_services/fam-embedding.control-service");
+Object.defineProperty(exports, "FAM_Embedding_ControlService", { enumerable: true, get: function () { return fam_embedding_control_service_1.FAM_Embedding_ControlService; } });
+var fam_openai_embedding_provider_1 = require("./_services/fam-openai-embedding.provider");
+Object.defineProperty(exports, "FAM_OpenAI_EmbeddingProvider", { enumerable: true, get: function () { return fam_openai_embedding_provider_1.FAM_OpenAI_EmbeddingProvider; } });
+var fam_lmstudio_embedding_provider_1 = require("./_services/fam-lmstudio-embedding.provider");
+Object.defineProperty(exports, "FAM_LMStudio_EmbeddingProvider", { enumerable: true, get: function () { return fam_lmstudio_embedding_provider_1.FAM_LMStudio_EmbeddingProvider; } });
+var fam_mock_embedding_provider_1 = require("./_services/fam-mock-embedding.provider");
+Object.defineProperty(exports, "FAM_Mock_EmbeddingProvider", { enumerable: true, get: function () { return fam_mock_embedding_provider_1.FAM_Mock_EmbeddingProvider; } });
+Object.defineProperty(exports, "FAM_MOCK_EMBEDDING_DIMS", { enumerable: true, get: function () { return fam_mock_embedding_provider_1.FAM_MOCK_EMBEDDING_DIMS; } });
+// SP-2.2 — Memory Vector Search (Mongo-persist + LVS hidratálás)
+var fam_vector_search_control_service_1 = require("./_services/fam-vector-search.control-service");
+Object.defineProperty(exports, "FAM_VectorSearch_ControlService", { enumerable: true, get: function () { return fam_vector_search_control_service_1.FAM_VectorSearch_ControlService; } });
+var fam_entry_data_service_1 = require("./_services/fam-entry.data-service");
+Object.defineProperty(exports, "FAM_Entry_DataService", { enumerable: true, get: function () { return fam_entry_data_service_1.FAM_Entry_DataService; } });
+var fam_store_registry_const_1 = require("./_collections/fam-store-registry.const");
+Object.defineProperty(exports, "FAM_STORE_REGISTRY", { enumerable: true, get: function () { return fam_store_registry_const_1.FAM_STORE_REGISTRY; } });
+Object.defineProperty(exports, "FAM_StoreRegistry_Util", { enumerable: true, get: function () { return fam_store_registry_const_1.FAM_StoreRegistry_Util; } });
+// SP-2.3 — presetek + per-tár/scope override
+var fam_embedding_preset_control_service_1 = require("./_services/fam-embedding-preset.control-service");
+Object.defineProperty(exports, "FAM_EmbeddingPreset_ControlService", { enumerable: true, get: function () { return fam_embedding_preset_control_service_1.FAM_EmbeddingPreset_ControlService; } });
+// SP-2.4 — re-embed + auto-embed pipeline + cost-cap
+var fam_embedding_pipeline_control_service_1 = require("./_services/fam-embedding-pipeline.control-service");
+Object.defineProperty(exports, "FAM_EmbeddingPipeline_ControlService", { enumerable: true, get: function () { return fam_embedding_pipeline_control_service_1.FAM_EmbeddingPipeline_ControlService; } });
+var fam_embedding_cost_control_service_1 = require("./_services/fam-embedding-cost.control-service");
+Object.defineProperty(exports, "FAM_EmbeddingCost_ControlService", { enumerable: true, get: function () { return fam_embedding_cost_control_service_1.FAM_EmbeddingCost_ControlService; } });
+// boot-hook (App.postProcess)
+var fam_embedding_bootstrap_control_service_1 = require("./_services/fam-embedding-bootstrap.control-service");
+Object.defineProperty(exports, "FAM_EmbeddingBootstrap_ControlService", { enumerable: true, get: function () { return fam_embedding_bootstrap_control_service_1.FAM_EmbeddingBootstrap_ControlService; } });

package/build/src/_modules/ingest/_collections/fam-content-hash.util.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ContentHash_Util = void 0;
+const tslib_1 = require("tslib");
+const crypto = tslib_1.__importStar(require("crypto"));
+/**
+ * `FAM_ContentHash_Util` (SP-4.3, dsgn-004 §4.1) — a delta-detection tartalom-ujjlenyomata. A
+ * `contentHash = SHA-256(normalizált content)`, ahol a normalizálás **trim + sor-vég-egységesítés**
+ * (`\r\n` → `\n`), hogy a whitespace-/sor-vég-zaj NE triggereljen fals `modified`-et (dsgn-004
+ * §8.6). A hash determinisztikus — ugyanaz a (normalizált) tartalom mindig ugyanazt a hash-t adja.
+ *
+ * **FIGYELEM — a normalizálás SZŰKEBB, mint az embedding-pipeline `sha256`-é** (ami `\s+ → ' '`
+ * összevonást is csinál a vektor-content-kompozícióhoz): a delta-detection a forrás-tartalom
+ * SOR-szerkezetét megőrzi (a `\r\n→\n` + trim elég a platform-/editor-zaj kiszűrésére, de a
+ * kódstruktúra-jelentős sortörések megmaradnak). Ez a util a delta-réteg SSOT-ja; a vektor-hash
+ * (`FAM_EmbeddingPipeline_ControlService.sha256`) attól FÜGGETLEN célt szolgál.
+ */
+class FAM_ContentHash_Util {
+    /**
+     * A normalizált tartalom SHA-256 ujjlenyomata hex-stringként (dsgn-004 §4.1). Determinisztikus;
+     * a `FAM_Entry.contentHash` mezőbe kerül. A normalizálás a `normalize`-on át (trim + `\r\n→\n`).
+     */
+    static hash(content) {
+        return crypto.createHash('sha256').update(FAM_ContentHash_Util.normalize(content)).digest('hex');
+    }
+    /**
+     * A delta-detection normalizálása (dsgn-004 §4.1): a sor-végeket egységesíti (`\r\n` és magányos
+     * `\r` → `\n`), majd trim-eli a teljes szöveget. A belső sortörések + indentáció MEGMARADNAK
+     * (csak a platform-/editor-zaj tűnik el), így a tartalmi változás detektálható marad.
+     */
+    static normalize(content) {
+        return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n').trim();
+    }
+}
+exports.FAM_ContentHash_Util = FAM_ContentHash_Util;

package/build/src/_modules/ingest/_collections/fam-file-routing.util.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_FileRouting_Util = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+/**
+ * `FAM_FileRouting_Util` (SP-4.1, dsgn-004 §2) — a file-típus-routing (intelligens szelekció): egy
+ * felderített fájlt a kiterjesztése / fájlnév-mintája alapján `documents` / `codebase` / `skip`
+ * cél-tárra route-ol. Statikus util (nincs DB-/service-függés).
+ *
+ * Routing-térkép (dsgn-004 §2):
+ * - `documents` ← `.md` `.mdx` `.txt` `.rst`
+ * - `codebase`  ← `.html` `.ts` `.tsx` `.js` `.jsx` `.py` `.css` `.scss` `.json` + config-fájlok
+ *                 (`*.config.*`, `tsconfig*.json`, `package.json`, `.eslintrc*`, `.prettierrc*`,
+ *                 `*.yml`/`*.yaml`/`*.toml`/`*.ini`, `Dockerfile`)
+ * - `skip`      ← minden egyéb (bináris, kép, lock-fájl, stb.) — verdikt nélkül, `filesSkipped`-ben.
+ *
+ * **A `.html` markup KIZÁRÓLAG `codebase`** (NEM `documents`) — a `documents` route a tartalmi
+ * dokumentációt célozza (`.md`/`.mdx`/`.txt`/`.rst`), nem a markup-ot (dsgn-004 §2). A
+ * `chunkStrategyFor` a route + kiterjesztés alapján adja a chunker-stratégiát (SP-4.2 dispatch).
+ */
+class FAM_FileRouting_Util {
+    /** Dokumentum-kiterjesztések → `documents` (dsgn-004 §2). */
+    static DOCUMENT_EXTENSIONS = ['.md', '.mdx', '.txt', '.rst'];
+    /** Kód-/markup-kiterjesztések → `codebase` (a `.html` markup IDE tartozik, dsgn-004 §2). */
+    static CODE_EXTENSIONS = [
+        '.html', '.ts', '.tsx', '.mts', '.js', '.jsx', '.py', '.css', '.scss', '.json',
+        '.yml', '.yaml', '.toml', '.ini',
+    ];
+    /** Markdown-kiterjesztések (a header-aware chunker célja, dsgn-004 §3.2). */
+    static MARKDOWN_EXTENSIONS = ['.md', '.mdx'];
+    /** TS-szemantikus chunker kiterjesztései (dsgn-004 §3.1). */
+    static TS_EXTENSIONS = ['.ts', '.tsx', '.mts', '.js', '.jsx'];
+    /** Extension-nélküli config-fájlnevek → `codebase` (dsgn-004 §2). */
+    static CONFIG_FILENAMES = ['dockerfile'];
+    /**
+     * Egy fájl route-verdiktje (dsgn-004 §2). A kiterjesztés-térkép, majd a config-fájlnév-minták
+     * (extension-nélküli `Dockerfile`, `*.config.*`, `tsconfig*.json`, `.eslintrc*`, `.prettierrc*`)
+     * → `codebase`; egyébként `skip`. A vizsgálat case-insensitive a kiterjesztésre/fájlnévre.
+     */
+    static route(relativePath) {
+        const fileName = path.basename(relativePath).toLowerCase();
+        const extension = path.extname(fileName);
+        if (FAM_FileRouting_Util.DOCUMENT_EXTENSIONS.includes(extension)) {
+            return fam_table_type_enum_1.FAM_Table.documents;
+        }
+        if (FAM_FileRouting_Util.CODE_EXTENSIONS.includes(extension)) {
+            return fam_table_type_enum_1.FAM_Table.codebase;
+        }
+        if (FAM_FileRouting_Util.isConfigFile(fileName)) {
+            return fam_table_type_enum_1.FAM_Table.codebase;
+        }
+        return 'skip';
+    }
+    /**
+     * Config-fájl-e a fájlnév (dsgn-004 §2): extension-nélküli ismert config (`Dockerfile`) VAGY
+     * a `*.config.*` / `tsconfig*.json` / `package.json` / `.eslintrc*` / `.prettierrc*` minta.
+     */
+    static isConfigFile(fileName) {
+        if (FAM_FileRouting_Util.CONFIG_FILENAMES.includes(fileName)) {
+            return true;
+        }
+        if (fileName === 'package.json' || fileName === 'package-lock.json') {
+            return true;
+        }
+        if (/^tsconfig.*\.json$/.test(fileName)) {
+            return true;
+        }
+        if (/\.config\./.test(fileName)) {
+            return true;
+        }
+        if (/^\.eslintrc/.test(fileName) || /^\.prettierrc/.test(fileName)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * A chunker-stratégia kulcsa egy fájlhoz (SP-4.2 dispatch, dsgn-004 §3). `ts` a TS-szemantikus
+     * (.ts/.tsx/.mts/.js/.jsx), `md` a markdown-header-aware (.md/.mdx), `generic` minden más
+     * `documents`/`codebase` fájlra (config/JSON/HTML-markup/.txt/.rst). A `route` előfeltétel:
+     * `skip` fájlra NEM hívandó.
+     */
+    static chunkStrategyFor(relativePath) {
+        const extension = path.extname(path.basename(relativePath).toLowerCase());
+        if (FAM_FileRouting_Util.TS_EXTENSIONS.includes(extension)) {
+            return 'ts';
+        }
+        if (FAM_FileRouting_Util.MARKDOWN_EXTENSIONS.includes(extension)) {
+            return 'md';
+        }
+        return 'generic';
+    }
+}
+exports.FAM_FileRouting_Util = FAM_FileRouting_Util;

package/build/src/_modules/ingest/_collections/fam-glob-match.util.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_GlobMatch_Util = void 0;
+/**
+ * `FAM_GlobMatch_Util` (SP-4.1) — minimál glob→regex matcher a scan ignore-/include-/exclude
+ * mintáihoz (dsgn-004 §6.2, dsgn-003 §3.1). Nincs külső glob-dependency (a `scan.ignorePatterns`
+ * a `**` / `*` / `?` szintaxist használja, dsgn-007 §4.5); a Node `fs`-bejárás minden útvonalra
+ * ezt a matchert hívja.
+ *
+ * **Boundary:** ez NEM teljes-értékű glob-engine (nincs `{a,b}` brace-expansion, nincs `[..]`
+ * char-class) — a scan-minták egyszerűek (`**​/node_modules/**`, `*.min.js`, `**​/.env.*`). A
+ * komplexebb minta-szintaxis (ha kell) BACKLOG / bedrock-igény. A matcher mind a teljes
+ * (projekt-relatív) útvonalra, mind a fájlnévre próbál — így a `*.min.js` (nincs `/`) az útvonal
+ * BÁRMELY szegmensére illeszkedik.
+ */
+class FAM_GlobMatch_Util {
+    /**
+     * Illeszkedik-e a (projekt-relatív, `/`-normalizált) útvonal a glob-mintára. A `**` bármennyi
+     * szegmens (a `/`-okat is átfedve), a `*` egy szegmensen belül bármennyi nem-`/` karakter, a
+     * `?` egyetlen nem-`/` karakter. A `/`-ot NEM tartalmazó minta (`*.min.js`) a fájlnévre (az
+     * útvonal utolsó szegmensére) is illeszkedhet.
+     */
+    static matches(relativePath, pattern) {
+        const normalizedPath = FAM_GlobMatch_Util.normalizeSlashes(relativePath);
+        const regex = FAM_GlobMatch_Util.toRegex(pattern);
+        if (regex.test(normalizedPath)) {
+            return true;
+        }
+        // A `/`-ot nem tartalmazó minta (pl. `*.min.js`) a fájlnévre is illeszkedhet.
+        if (!pattern.includes('/')) {
+            const fileName = normalizedPath.split('/').pop() ?? normalizedPath;
+            return FAM_GlobMatch_Util.toRegex(pattern).test(fileName);
+        }
+        return false;
+    }
+    /** Illeszkedik-e az útvonal a minták BÁRMELYIKÉRE (üres lista → `false`). */
+    static matchesAny(relativePath, patterns) {
+        return patterns.some((pattern) => FAM_GlobMatch_Util.matches(relativePath, pattern));
+    }
+    /**
+     * Egy glob-minta → `RegExp`. A regex-metakaraktereket escape-eli, majd a glob-wildcardokat
+     * (`**` / `*` / `?`) regex-fragmentekre cseréli. A `**` a `/`-okat is átfedi (`.*`); a `*` egy
+     * szegmensen belül marad (`[^/]*`); a `?` egyetlen nem-`/` karakter (`[^/]`). Teljes-string
+     * anchor (`^...$`).
+     */
+    static toRegex(pattern) {
+        const normalized = FAM_GlobMatch_Util.normalizeSlashes(pattern);
+        let regexSource = '';
+        for (let i = 0; i < normalized.length; i++) {
+            const char = normalized[i];
+            if (char === '*') {
+                if (normalized[i + 1] === '*') {
+                    // `**` (esetleg záró `/`-val) → bármennyi szegmens (a `/`-okat átfedve).
+                    i++;
+                    if (normalized[i + 1] === '/') {
+                        i++;
+                    }
+                    regexSource += '.*';
+                }
+                else {
+                    // `*` → egy szegmensen belül bármennyi nem-`/` karakter.
+                    regexSource += '[^/]*';
+                }
+                continue;
+            }
+            if (char === '?') {
+                regexSource += '[^/]';
+                continue;
+            }
+            // Regex-metakarakterek escape-elése (a `.` / `+` / `(` stb. literál legyen).
+            regexSource += FAM_GlobMatch_Util.escapeRegexChar(char);
+        }
+        return new RegExp(`^${regexSource}$`);
+    }
+    /** Egyetlen karakter regex-escape-je (a glob-literál szegmensekhez). */
+    static escapeRegexChar(char) {
+        return /[.*+?^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
+    }
+    /** A backslash-eket előre-perjelre normalizálja (Windows-útvonalak; a glob mindig `/`-os). */
+    static normalizeSlashes(value) {
+        return value.replace(/\\/g, '/');
+    }
+}
+exports.FAM_GlobMatch_Util = FAM_GlobMatch_Util;

package/build/src/_modules/ingest/_collections/fam-md-chunker.util.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_MdChunker_Util = void 0;
+/**
+ * `FAM_MdChunker_Util` (SP-4.2, dsgn-004 §3.2) — markdown-header-tudatos chunker `.md/.mdx`-re.
+ *
+ * **REUSE-DÖNTÉS (dsgn-004 §3.2 + feedback_read_actual_reference_code):** a Dynamo
+ * `DyNTS_DAI_DocChunking_Util.chunkMdContent()` a TÉNYLEGES forráskód szerint **NEM** plain
+ * `(content: string) => chunks` API — ClickUp-domain-objektumot követel (`DyNTS_DAI_DocPage` a
+ * `documentId`/`externalPageId`/`parentedPath`/`allFlaggedParents`-szel), `getPageLink` callback-et,
+ * `DyNTS_DAI_DocChunk` Mongo-DataModel-eket ad vissza (`pageLink`/`pageId`-vel), `CCAP-CUC-*`
+ * hibát dob ha `documentId`/`_id` hiányzik, és a méretet a ClickUp `DyNTS_global_settings.docChunking`-ből
+ * veszi (NEM a FAM `chunk.md.*` config-ból). Ezért NEM közvetlenül használható egy lokális fájl-scanre.
+ * A header-tudatos ALGORITMUS (heading-hierarchia + break-pointok) viszont kiváló — ezt a CCAP
+ * `PS_MarkdownChunker_Util` projekt-lokális portjával reprodukáljuk (a CCAP maga is ezt az
+ * algoritmust képezi le a Dynamo break-point-mintából). Méret a config-ból (`chunk.md.*`),
+ * default `1200/150/80`.
+ *
+ * - Minden szakasz `chunkType = 'heading-section'`.
+ * - A `headingPath` a teljes heading-LÁNCOT őrzi (`['# H1','## H2','### H3']`) — kontextus a
+ *   retrieval-höz (dsgn-005) és a megjelenítéshez.
+ * - Heading nélküli tartalom → egyetlen szekció üres `headingPath`-szal (a sliding-window a
+ *   nagy-szekció ágon, dsgn-004 §3.2).
+ */
+class FAM_MdChunker_Util {
+    static HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
+    /**
+     * Egy markdown forrás chunkolása heading-hierarchia mentén (dsgn-004 §3.2). Üres tartalom →
+     * üres lista (a dispatcher tiny-fallback-je veszi át). A `maxSize` feletti szekció a
+     * heading-prefixet megőrző sliding-window-ra bomlik.
+     */
+    static chunkText(text, sizing) {
+        if (!text || !text.trim()) {
+            return [];
+        }
+        const sections = FAM_MdChunker_Util.splitIntoSections(text);
+        const chunks = [];
+        for (const section of sections) {
+            const headingPrefix = section.headingPath.length ? section.headingPath.join('\n') + '\n\n' : '';
+            const sectionContent = headingPrefix + section.content;
+            if (sectionContent.length <= sizing.maxSize) {
+                if (sectionContent.trim().length >= sizing.minSize) {
+                    chunks.push({
+                        content: sectionContent.trim(),
+                        position: {
+                            charStart: section.charStart,
+                            charEnd: section.charEnd,
+                            lineStart: section.lineStart,
+                            lineEnd: section.lineEnd,
+                        },
+                        chunkType: 'heading-section',
+                        headingPath: section.headingPath,
+                    });
+                }
+                continue;
+            }
+            chunks.push(...FAM_MdChunker_Util.slidingWithinSection(section, headingPrefix, sizing));
+        }
+        return chunks;
+    }
+    /** A forrás szekciókra bontása heading-ek mentén (a heading-stack tartja a hierarchiát). */
+    static splitIntoSections(text) {
+        const lines = text.split(/\r?\n/);
+        const sections = [];
+        const headingStack = [];
+        let currentContent = '';
+        let currentCharStart = 0;
+        let currentLineStart = 1;
+        let charCursor = 0;
+        for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+            const line = lines[lineIdx];
+            const headingMatch = line.match(FAM_MdChunker_Util.HEADING_REGEX);
+            if (headingMatch) {
+                if (currentContent.trim()) {
+                    sections.push({
+                        headingPath: FAM_MdChunker_Util.snapshotStack(headingStack),
+                        content: currentContent.trim(),
+                        charStart: currentCharStart,
+                        charEnd: charCursor,
+                        lineStart: currentLineStart,
+                        lineEnd: lineIdx,
+                    });
+                }
+                const level = headingMatch[1].length;
+                const headingText = headingMatch[2].trim();
+                while (headingStack.length && headingStack[headingStack.length - 1].level >= level) {
+                    headingStack.pop();
+                }
+                headingStack.push({ level: level, text: headingText });
+                currentContent = '';
+                currentCharStart = charCursor;
+                currentLineStart = lineIdx + 1;
+            }
+            else {
+                currentContent += (currentContent ? '\n' : '') + line;
+            }
+            charCursor += line.length + 1;
+        }
+        if (currentContent.trim()) {
+            sections.push({
+                headingPath: FAM_MdChunker_Util.snapshotStack(headingStack),
+                content: currentContent.trim(),
+                charStart: currentCharStart,
+                charEnd: charCursor,
+                lineStart: currentLineStart,
+                lineEnd: lines.length,
+            });
+        }
+        // Nincs heading: az egész szöveg egy szekció (üres heading-lánc).
+        if (!sections.length && text.trim()) {
+            sections.push({
+                headingPath: [],
+                content: text.trim(),
+                charStart: 0,
+                charEnd: text.length,
+                lineStart: 1,
+                lineEnd: lines.length,
+            });
+        }
+        return sections;
+    }
+    /** A heading-stack pillanatfelvétele teljes heading-láncként (`['# H1','## H2']`). */
+    static snapshotStack(stack) {
+        return stack.map((heading) => '#'.repeat(heading.level) + ' ' + heading.text);
+    }
+    /** Nagy szekció sliding-window-ja a heading-prefixet megőrizve (sorvégre igazított break). */
+    static slidingWithinSection(section, headingPrefix, sizing) {
+        const chunks = [];
+        const available = Math.max(1, sizing.maxSize - headingPrefix.length);
+        const body = section.content;
+        let offset = 0;
+        while (offset < body.length) {
+            const end = Math.min(offset + available, body.length);
+            let segment = body.slice(offset, end);
+            // Sorvégnél törünk (ne szó közepén), ha nem a szekció vége.
+            if (end < body.length) {
+                const lastNewline = segment.lastIndexOf('\n');
+                if (lastNewline > available * 0.3) {
+                    segment = segment.slice(0, lastNewline);
+                }
+            }
+            const fullText = (headingPrefix + segment.trim()).trim();
+            if (fullText.length >= sizing.minSize) {
+                chunks.push({
+                    content: fullText,
+                    position: {
+                        charStart: section.charStart + offset,
+                        charEnd: section.charStart + offset + segment.length,
+                        lineStart: section.lineStart,
+                        lineEnd: section.lineEnd,
+                    },
+                    chunkType: 'heading-section',
+                    headingPath: section.headingPath,
+                });
+            }
+            if (offset + segment.length >= body.length) {
+                break;
+            }
+            offset += Math.max(1, segment.length - sizing.overlap);
+        }
+        return chunks;
+    }
+}
+exports.FAM_MdChunker_Util = FAM_MdChunker_Util;