@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/ingest/_collections/fam-scan-path.util.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScanPath_Util = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+/**
+ * `FAM_ScanPath_Util` (SP-4.1, dsgn-004 §6.1) — a scan-réteg path-traversal védelme. A scan
+ * LOKÁLIS fájlrendszert olvas, ezért minden bejárt fájl feloldott **valódi** abszolút útvonalának
+ * (realpath) a scan-gyökér alatt KELL maradnia — `..`-szegmens / symlink-escape → `FAM-SCAN-*`
+ * hiba (dsgn-008 §6.1). A `sourceFilePath` a gyökértől relatívan számolódik (a chunk-mezőre).
+ *
+ * **Symlink-escape (a `MP-4-detailed` kockázat):** NEM string-prefix összevetés (azt a junction/
+ * symlink megkerüli), hanem a `fs.realpathSync`-cal feloldott VALÓDI útvonalat veti össze a
+ * (szintén realpath-olt) gyökérrel, `path.relative` + szegmens-vizsgálattal. Statikus util — nincs
+ * DB-/service-függés (a `FAM_Error_Util.create` csak megépíti a hibát, a hívó dobja/emittálja).
+ */
+class FAM_ScanPath_Util {
+    /**
+     * Egy scan-gyökér feloldott VALÓDI abszolút útvonala (`realpath`). A gyökérnek léteznie kell;
+     * nem-létező / olvashatatlan gyökér → `FAM-SCAN-READ-001` (a run `failed`). A többi útvonal
+     * ehhez a kanonikus gyökérhez méri magát.
+     */
+    static resolveRoot(rootPath, issuer) {
+        try {
+            return fs.realpathSync(path.resolve(rootPath));
+        }
+        catch (error) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.scanRead,
+                message: `A scan-gyökér nem oldható fel / nem olvasható: '${rootPath}'. `
+                    + 'Ellenőrizd, hogy az útvonal létezik és olvasható.',
+                issuer: issuer,
+                context: { operation: 'resolve-scan-root', sourceFilePath: rootPath },
+                cause: error,
+            });
+        }
+    }
+    /**
+     * Biztosítja, hogy a `candidatePath` valódi feloldott útvonala a `resolvedRoot` ALATT (vagy
+     * azonos vele) maradjon (dsgn-004 §6.1). Escape (`..`/symlink a gyökéren kívülre) →
+     * `FAM-SCAN-READ-001` hiba. Visszaadja a feloldott valódi abszolút útvonalat (a hívó ezt
+     * használja olvasásra + a relatív-útvonal számításhoz).
+     */
+    static assertInsideRoot(resolvedRoot, candidatePath, issuer) {
+        let realCandidate;
+        try {
+            realCandidate = fs.realpathSync(path.resolve(candidatePath));
+        }
+        catch (error) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.scanRead,
+                message: `A scan-útvonal nem oldható fel / nem olvasható: '${candidatePath}'.`,
+                issuer: issuer,
+                context: { operation: 'assert-inside-root', sourceFilePath: candidatePath },
+                cause: error,
+            });
+        }
+        if (!FAM_ScanPath_Util.isInside(resolvedRoot, realCandidate)) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.scanRead,
+                message: `Path-traversal védelem: a feloldott útvonal ('${realCandidate}') a scan-gyökéren `
+                    + `('${resolvedRoot}') KÍVÜL esik ('..'-szegmens vagy symlink-escape). A scan elutasítva.`,
+                issuer: issuer,
+                context: { operation: 'path-traversal-guard', sourceFilePath: candidatePath },
+            });
+        }
+        return realCandidate;
+    }
+    /**
+     * A `child` valódi-útvonal a `root` ALATT van-e (vagy azonos). A `path.relative` eredménye
+     * NEM kezdődhet `..`-tal és nem lehet abszolút (más meghajtó) — ez a szegmens-szintű, NEM
+     * string-prefix összevetés (a string-prefix `/a/bc`-t `/a/b` alá sorolná tévesen).
+     */
+    static isInside(root, child) {
+        const relative = path.relative(root, child);
+        return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+    }
+    /**
+     * A `resolvedRoot`-tól relatív, `/`-normalizált projekt-relatív útvonal (a `sourceFilePath`
+     * chunk-mezőé, dsgn-004 §3). Windows-on a backslash-eket előre-perjelre normalizálja (stabil,
+     * platform-független `sourceFilePath` a delta-kulcshoz).
+     */
+    static toRelative(resolvedRoot, absolutePath) {
+        const relative = path.relative(resolvedRoot, absolutePath);
+        return relative.replace(/\\/g, '/');
+    }
+}
+exports.FAM_ScanPath_Util = FAM_ScanPath_Util;

package/build/src/_modules/ingest/_collections/fam-secret-exclude.util.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_SecretExclude_Util = void 0;
+/**
+ * `FAM_SecretExclude_Util` (SP-4.1, dsgn-004 §6.3) — a scan-réteg **fájlnév-/útvonal-alapú**
+ * secret-kizárása. A felsorolt minták (`.env*`, `*.key`, `*.pem`, `*.p12`, `id_rsa*`, `*secret*`,
+ * `*credential*`, `*.crt`, `secrets/` mappa) **SOHA** nem ingestálódnak; a kizárás a file-típus-
+ * routing **ELŐTT** fut, és a kizárt fájlok a `filesSkipped`-be számolódnak (audit, NEM néma).
+ *
+ * **HATÁR (dsgn-004 §6 megjegyzés + `MP-4-detailed` kockázat) — KIFEJEZETTEN BACKLOG:** ez CSAK
+ * fájlnév-/útvonal-alapú kizárás. A **tartalmi** PII/secret-detektálás (a fájlon BELÜLI titkok
+ * kiszűrése, pl. egy `.ts`-be ágyazott API-key) NINCS implementálva MVP1-ben — false sense of
+ * safety elkerülése végett ezt itt + a run-riportban egyértelműen jelezzük. A tartalmi szkennelés
+ * későbbi fázis (BACKLOG / bedrock-igény).
+ */
+class FAM_SecretExclude_Util {
+    /**
+     * A beépített secret-fájlnév-minták (dsgn-004 §6.3). Ezek a `scan.ignorePatterns` config
+     * biztonsági default-jával átfedők (dsgn-007 §4.5 `SCAN_IGNORE_PATTERNS_DEFAULT`), de a scan
+     * ettől FÜGGETLENÜL is alkalmazza őket (a config-override NEM kapcsolhatja ki a secret-védelmet).
+     * A vizsgálat a fájlnévre (regex) + az útvonal-szegmensekre (`secrets/`) megy.
+     */
+    static SECRET_FILENAME_PATTERNS = [
+        /^\.env(\..*)?$/i, // .env, .env.local, .env.production, ...
+        /\.key$/i, // *.key
+        /\.pem$/i, // *.pem
+        /\.p12$/i, // *.p12
+        /\.crt$/i, // *.crt (cert)
+        /\.pfx$/i, // *.pfx (cert)
+        /^id_rsa.*$/i, // id_rsa, id_rsa.pub, ...
+        /^id_ed25519.*$/i, // id_ed25519, id_ed25519.pub
+        /secret/i, // *secret* (bárhol a fájlnévben)
+        /credential/i, // *credential* (bárhol a fájlnévben)
+    ];
+    /** A secret-mappák (az útvonal BÁRMELY szegmense — pl. `secrets/`, `.ssh/`). */
+    static SECRET_DIR_SEGMENTS = ['secrets', '.ssh', '.gnupg'];
+    /**
+     * Secret-e a (projekt-relatív, `/`-normalizált) útvonal — fájlnév-minta VAGY secret-mappa-
+     * szegmens alapján (dsgn-004 §6.3). `true` → SOHA nem ingestálódik (`filesSkipped`, audit).
+     */
+    static isSecret(relativePath) {
+        const normalized = relativePath.replace(/\\/g, '/');
+        const segments = normalized.split('/').filter((segment) => segment.length);
+        const fileName = segments[segments.length - 1] ?? normalized;
+        // (1) Secret-mappa az útvonal bármely (nem-utolsó) szegmensében.
+        const dirSegments = segments.slice(0, -1).map((segment) => segment.toLowerCase());
+        if (dirSegments.some((segment) => FAM_SecretExclude_Util.SECRET_DIR_SEGMENTS.includes(segment))) {
+            return true;
+        }
+        // (2) Secret-fájlnév-minta.
+        return FAM_SecretExclude_Util.SECRET_FILENAME_PATTERNS.some((pattern) => pattern.test(fileName));
+    }
+}
+exports.FAM_SecretExclude_Util = FAM_SecretExclude_Util;

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

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_SlidingChunker_Util = void 0;
+/**
+ * `FAM_SlidingChunker_Util` (SP-4.2, dsgn-004 §3.3) — generic sliding-window chunker minden dedikált
+ * stratégia nélküli `documents`/`codebase` fájlra (config, JSON, plain text, **`.html` markup**,
+ * `.txt`, `.rst`). A CCAP `PS_SimpleChunker_Util` projekt-lokális portja: bekezdés-határra
+ * (dupla-újsor) próbál osztani, majd a chunk-méret-plafonig épít, overlap-pal lép tovább. A
+ * break-pointokat sor-/bekezdés-határra igazítja (NEM nyers karakter-vágás), de hierarchia-megőrzés
+ * NÉLKÜL (`headingPath = []`). Méret a config-ból (`chunk.generic.*`), default `1200/150`.
+ *
+ * `chunkType = 'generic'`. A `position.charStart`/`charEnd` a forrás-szöveg tényleges karakter-
+ * tartományára mutat (a bekezdés-pozíció `indexOf`-fal feloldva, a CCAP-minta szerint).
+ */
+class FAM_SlidingChunker_Util {
+    /**
+     * Egy strukturálatlan szöveg chunkolása (dsgn-004 §3.3). Üres → üres lista (a dispatcher
+     * tiny-fallback-je veszi át). Bekezdés-alapú összeépítés overlap-pal; egy óriás-bekezdés a
+     * `maxSize * 1.5` felett kényszer-emittál (ne fusson el a memória).
+     */
+    static chunkText(text, sizing) {
+        if (!text || !text.trim()) {
+            return [];
+        }
+        const paragraphs = text.split(/\r?\n\r?\n/).filter((paragraph) => paragraph.trim().length);
+        const chunks = [];
+        let currentText = '';
+        let currentCharStart = 0;
+        let charCursor = 0;
+        for (const paragraph of paragraphs) {
+            const paragraphStart = text.indexOf(paragraph, charCursor);
+            if (paragraphStart >= 0) {
+                charCursor = paragraphStart;
+            }
+            if (currentText.length && currentText.length + paragraph.length + 2 > sizing.maxSize) {
+                FAM_SlidingChunker_Util.emit(chunks, currentText.trim(), currentCharStart, sizing.minSize);
+                if (currentText.length > sizing.overlap) {
+                    currentText = currentText.slice(-sizing.overlap);
+                    currentCharStart = Math.max(0, charCursor - sizing.overlap);
+                }
+                else {
+                    currentText = '';
+                    currentCharStart = charCursor;
+                }
+            }
+            if (!currentText) {
+                currentCharStart = charCursor;
+            }
+            currentText += (currentText ? '\n\n' : '') + paragraph;
+            charCursor = paragraphStart >= 0 ? paragraphStart + paragraph.length : charCursor + paragraph.length;
+            // Egy óriás-bekezdés is túl nagy → kényszer-emit.
+            if (currentText.length > sizing.maxSize * 1.5) {
+                FAM_SlidingChunker_Util.emit(chunks, currentText.trim(), currentCharStart, sizing.minSize);
+                currentText = '';
+                currentCharStart = charCursor;
+            }
+        }
+        if (currentText.trim().length >= sizing.minSize) {
+            FAM_SlidingChunker_Util.emit(chunks, currentText.trim(), currentCharStart, sizing.minSize);
+        }
+        return chunks;
+    }
+    /** Egy chunk hozzáadása `chunkType='generic'`-kel (zaj-szűrés a `minSize`-ra). */
+    static emit(chunks, content, charStart, minSize) {
+        if (content.length < minSize) {
+            return;
+        }
+        chunks.push({
+            content: content,
+            position: { charStart: charStart, charEnd: charStart + content.length },
+            chunkType: 'generic',
+            headingPath: [],
+        });
+    }
+}
+exports.FAM_SlidingChunker_Util = FAM_SlidingChunker_Util;

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

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_TsChunker_Util = void 0;
+/**
+ * `FAM_TsChunker_Util` (SP-4.2, dsgn-004 §3.1, **BFR-AM-005 workaround**) — TypeScript-szemantikus
+ * chunker `.ts/.tsx/.mts/.js/.jsx`-re. A CCAP `PS_TypeScriptChunker_Util` regex/brace-depth
+ * megközelítésének projekt-lokális portja: import-csoport → top-level deklarációk (class/interface/
+ * enum/type/function/const-export) → osztály-blokk (a metódus-bontás brace-depth-fel a nagy-blokk
+ * ágon történik) → JSDoc + `@Decorator` a következő kód-chunkkal együtt → nagy blokk soronkénti
+ * sliding-window-ra bomlik. A méret-konstansok a config-ból (`chunk.ts.*`), default `1500/100/50`.
+ *
+ * **BFR-AM-005 (dsgn-004 §3.1 megjegyzés):** a regex/brace-depth téved string-literálban lévő `{`/`}`
+ * vagy template-literál esetén — a `countBraces` konzervatívan kihagyja a string-/line-comment-
+ * tartalmat, és a tiny-fallback safety-net (a dispatcher) elkapja a degenerált eseteket. Az
+ * AST-pontos darabolás (tree-sitter / TS-compiler) bedrock-szinten készül (MP-15).
+ *
+ * **headingPath = kód-symbol-lánc** (dsgn-001 megengedi: "MD heading-lánc VAGY kód-symbol-lánc"):
+ * pl. `['class:FooService']`; a nagy-blokk sub-chunkjai öröklik a szülő symbol-láncát + a
+ * `chunkType`-ot.
+ */
+class FAM_TsChunker_Util {
+    static IMPORT_LINE = /^import\s/;
+    static EXPORT_FROM_LINE = /^export\s.*\sfrom\s/;
+    static CLASS_START = /^(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+(\w+)/;
+    static INTERFACE_START = /^(?:export\s+)?interface\s+(\w+)/;
+    static ENUM_START = /^(?:export\s+)?(?:const\s+)?enum\s+(\w+)/;
+    static TYPE_ALIAS_START = /^(?:export\s+)?type\s+(\w+)\s*=/;
+    static STANDALONE_FUNCTION = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+(\w+)/;
+    static CONST_EXPORT = /^(?:export\s+)?const\s+(\w+)/;
+    static DECORATOR_LINE = /^\s*@\w+/;
+    static JSDOC_OPEN = /^\s*\/\*\*/;
+    static JSDOC_CLOSE = /\*\//;
+    /**
+     * Egy TS/JS forrás chunkolása szemantikus blokkok mentén (dsgn-004 §3.1). Üres / whitespace-only
+     * tartalom → üres lista (a dispatcher tiny-fallback-je veszi át). A nagy (max-size feletti)
+     * blokkok soronkénti sliding-window-ra bomlanak (örökölt `chunkType` + symbol-`headingPath`).
+     */
+    static chunkText(text, sizing) {
+        if (!text || !text.trim()) {
+            return [];
+        }
+        const lines = text.split(/\r?\n/);
+        const blocks = FAM_TsChunker_Util.identifyBlocks(lines);
+        const chunks = [];
+        for (const block of blocks) {
+            const blockText = block.lines.join('\n');
+            const headingPath = FAM_TsChunker_Util.buildHeadingPath(block);
+            if (blockText.length <= sizing.maxSize) {
+                if (blockText.trim().length >= sizing.minSize) {
+                    chunks.push({
+                        content: blockText,
+                        position: {
+                            charStart: block.charStart,
+                            charEnd: block.charStart + blockText.length,
+                            lineStart: block.lineStart,
+                            lineEnd: block.lineEnd,
+                        },
+                        chunkType: block.blockType,
+                        headingPath: headingPath,
+                    });
+                }
+                continue;
+            }
+            // Túl nagy blokk → soronkénti sliding-window (örökölt chunkType + symbol-lánc).
+            chunks.push(...FAM_TsChunker_Util.splitLargeBlock(block, sizing, headingPath));
+        }
+        return chunks;
+    }
+    /** Pass 1: top-level blokkok azonosítása soronkénti feldolgozással (brace-depth tracking). */
+    static identifyBlocks(lines) {
+        const blocks = [];
+        let currentBlock = undefined;
+        let braceDepth = 0;
+        let inBlockBody = false;
+        let jsdocBuffer = [];
+        let jsdocStartLine = 0;
+        let decoratorBuffer = [];
+        let inJsdoc = false;
+        let charCursor = 0;
+        let importLines = [];
+        let importStartLine = -1;
+        let importCharStart = 0;
+        for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+            const line = lines[lineIdx];
+            const trimmed = line.trimStart();
+            // -- JSDoc (a következő kód-chunkkal együtt marad, dsgn-004 §3.1 (4)) --
+            if (!inJsdoc && FAM_TsChunker_Util.JSDOC_OPEN.test(trimmed)) {
+                inJsdoc = true;
+                jsdocBuffer = [line];
+                jsdocStartLine = lineIdx;
+                if (FAM_TsChunker_Util.JSDOC_CLOSE.test(trimmed)) {
+                    inJsdoc = false;
+                }
+                charCursor += line.length + 1;
+                continue;
+            }
+            if (inJsdoc) {
+                jsdocBuffer.push(line);
+                if (FAM_TsChunker_Util.JSDOC_CLOSE.test(trimmed)) {
+                    inJsdoc = false;
+                }
+                charCursor += line.length + 1;
+                continue;
+            }
+            // -- Blokk body-jában (brace-depth tracking) --
+            if (inBlockBody && currentBlock) {
+                currentBlock.lines.push(line);
+                currentBlock.lineEnd = lineIdx + 1;
+                braceDepth += FAM_TsChunker_Util.countBraces(line);
+                if (braceDepth <= 0) {
+                    inBlockBody = false;
+                    blocks.push(currentBlock);
+                    currentBlock = undefined;
+                    braceDepth = 0;
+                }
+                charCursor += line.length + 1;
+                continue;
+            }
+            // -- Decorator (a következő kód-chunkkal együtt) --
+            if (FAM_TsChunker_Util.DECORATOR_LINE.test(trimmed)) {
+                decoratorBuffer.push(line);
+                charCursor += line.length + 1;
+                continue;
+            }
+            // -- Import-csoport (dsgn-004 §3.1 (1)) --
+            if (FAM_TsChunker_Util.IMPORT_LINE.test(trimmed) || FAM_TsChunker_Util.EXPORT_FROM_LINE.test(trimmed)) {
+                jsdocBuffer = [];
+                decoratorBuffer = [];
+                if (importStartLine === -1) {
+                    importStartLine = lineIdx;
+                    importCharStart = charCursor;
+                }
+                importLines.push(line);
+                charCursor += line.length + 1;
+                continue;
+            }
+            // -- Import-csoport lezárása (más jön) --
+            if (importLines.length) {
+                blocks.push({
+                    blockType: 'imports',
+                    lines: importLines,
+                    lineStart: importStartLine + 1,
+                    lineEnd: importStartLine + importLines.length,
+                    charStart: importCharStart,
+                });
+                importLines = [];
+                importStartLine = -1;
+            }
+            // -- Üres sor → pufferek ürítése --
+            if (!trimmed) {
+                jsdocBuffer = [];
+                decoratorBuffer = [];
+                charCursor += line.length + 1;
+                continue;
+            }
+            // -- Top-level deklaráció detektálás --
+            const detected = FAM_TsChunker_Util.detectDeclaration(trimmed);
+            const blockLines = [...jsdocBuffer, ...decoratorBuffer, line];
+            const blockStartLine = jsdocBuffer.length ? jsdocStartLine + 1 : lineIdx + 1;
+            const prefixChars = [...jsdocBuffer, ...decoratorBuffer]
+                .reduce((sum, bufferLine) => sum + bufferLine.length + 1, 0);
+            const blockCharStart = Math.max(0, charCursor - prefixChars);
+            braceDepth = FAM_TsChunker_Util.countBraces(line);
+            if (braceDepth > 0) {
+                // Több-soros blokk-body folytatódik.
+                inBlockBody = true;
+                currentBlock = {
+                    blockType: detected.blockType,
+                    lines: blockLines,
+                    lineStart: blockStartLine,
+                    lineEnd: lineIdx + 1,
+                    charStart: blockCharStart,
+                    entityName: detected.entityName,
+                };
+            }
+            else {
+                // Egy-soros blokk (type-alias / rövid const).
+                if (blockLines.join('\n').trim().length) {
+                    blocks.push({
+                        blockType: detected.blockType,
+                        lines: blockLines,
+                        lineStart: blockStartLine,
+                        lineEnd: lineIdx + 1,
+                        charStart: blockCharStart,
+                        entityName: detected.entityName,
+                    });
+                }
+                braceDepth = 0;
+            }
+            jsdocBuffer = [];
+            decoratorBuffer = [];
+            charCursor += line.length + 1;
+        }
+        // -- Maradék import-csoport --
+        if (importLines.length) {
+            blocks.push({
+                blockType: 'imports',
+                lines: importLines,
+                lineStart: importStartLine + 1,
+                lineEnd: importStartLine + importLines.length,
+                charStart: importCharStart,
+            });
+        }
+        // -- Maradék nyitott blokk (lezáratlan brace) --
+        if (currentBlock) {
+            blocks.push(currentBlock);
+        }
+        return blocks;
+    }
+    /** Egy sor → a kezdő-deklaráció típusa + neve (a `chunkType` + symbol-`headingPath`-hoz). */
+    static detectDeclaration(trimmed) {
+        const classMatch = trimmed.match(FAM_TsChunker_Util.CLASS_START);
+        if (classMatch) {
+            return { blockType: 'class', entityName: classMatch[1] };
+        }
+        const ifaceMatch = trimmed.match(FAM_TsChunker_Util.INTERFACE_START);
+        if (ifaceMatch) {
+            return { blockType: 'interface', entityName: ifaceMatch[1] };
+        }
+        const enumMatch = trimmed.match(FAM_TsChunker_Util.ENUM_START);
+        if (enumMatch) {
+            return { blockType: 'enum', entityName: enumMatch[1] };
+        }
+        const typeMatch = trimmed.match(FAM_TsChunker_Util.TYPE_ALIAS_START);
+        if (typeMatch) {
+            return { blockType: 'type', entityName: typeMatch[1] };
+        }
+        const funcMatch = trimmed.match(FAM_TsChunker_Util.STANDALONE_FUNCTION);
+        if (funcMatch) {
+            return { blockType: 'function', entityName: funcMatch[1] };
+        }
+        const constMatch = trimmed.match(FAM_TsChunker_Util.CONST_EXPORT);
+        if (constMatch) {
+            return { blockType: 'function', entityName: constMatch[1] };
+        }
+        return { blockType: 'generic' };
+    }
+    /**
+     * Brace-mélység egy sorban (nyitó − záró `{}`), a string-literálok + line-comment kihagyásával
+     * (BFR-AM-005 konzervatív megközelítés — NEM AST). Template-literál `${...}` belsejét nem
+     * elemzi mélyen; a degenerált eseteket a tiny-fallback safety-net + a max-size sliding fedi.
+     */
+    static countBraces(line) {
+        let depth = 0;
+        let inString = false;
+        let stringChar = '';
+        for (let i = 0; i < line.length; i++) {
+            const char = line[i];
+            const prev = i > 0 ? line[i - 1] : '';
+            if (!inString && char === '/' && line[i + 1] === '/') {
+                break;
+            }
+            if (!inString && (char === '"' || char === '\'' || char === '`')) {
+                inString = true;
+                stringChar = char;
+                continue;
+            }
+            if (inString && char === stringChar && prev !== '\\') {
+                inString = false;
+                continue;
+            }
+            if (inString) {
+                continue;
+            }
+            if (char === '{') {
+                depth++;
+            }
+            if (char === '}') {
+                depth--;
+            }
+        }
+        return depth;
+    }
+    /** Nagy blokk soronkénti sliding-window-ja (örökölt chunkType + symbol-`headingPath`). */
+    static splitLargeBlock(block, sizing, headingPath) {
+        const chunks = [];
+        const lines = block.lines;
+        const overlapLines = Math.max(1, Math.floor(sizing.overlap / 80));
+        let startIdx = 0;
+        while (startIdx < lines.length) {
+            let currentText = '';
+            let endIdx = startIdx;
+            while (endIdx < lines.length) {
+                const candidate = currentText + (currentText ? '\n' : '') + lines[endIdx];
+                if (candidate.length > sizing.maxSize && currentText.length) {
+                    break;
+                }
+                currentText = candidate;
+                endIdx++;
+            }
+            if (currentText.trim().length >= sizing.minSize) {
+                chunks.push({
+                    content: currentText,
+                    position: {
+                        charStart: block.charStart,
+                        charEnd: block.charStart + currentText.length,
+                        lineStart: block.lineStart + startIdx,
+                        lineEnd: block.lineStart + endIdx - 1,
+                    },
+                    chunkType: block.blockType,
+                    headingPath: headingPath,
+                });
+            }
+            startIdx = Math.max(startIdx + 1, endIdx - overlapLines);
+        }
+        return chunks;
+    }
+    /** A symbol-`headingPath` egy blokkhoz (`['class:Foo']`); generic / névtelen → üres tömb. */
+    static buildHeadingPath(block) {
+        if (block.entityName && block.blockType !== 'generic' && block.blockType !== 'imports') {
+            return [`${block.blockType}:${block.entityName}`];
+        }
+        return [];
+    }
+}
+exports.FAM_TsChunker_Util = FAM_TsChunker_Util;

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

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

package/build/src/_modules/ingest/_services/fam-chunker.control-service.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Chunker_ControlService = void 0;
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const fam_file_routing_util_1 = require("../_collections/fam-file-routing.util");
+const fam_ts_chunker_util_1 = require("../_collections/fam-ts-chunker.util");
+const fam_md_chunker_util_1 = require("../_collections/fam-md-chunker.util");
+const fam_sliding_chunker_util_1 = require("../_collections/fam-sliding-chunker.util");
+/**
+ * `FAM_Chunker_ControlService` (SP-4.2, dsgn-004 §3) — a chunker-dispatch. A route + kiterjesztés
+ * alapján stratégiát választ (TS-semantic | markdown | generic-sliding), a méret-konstansokat a
+ * config-ból oldja fel (`resolveConfig(key, {table, scopePath})`, dsgn-007 — default a CCAP-érték),
+ * a chunker nyers kimenetét (`FAM_RawChunk[]`) a `FAM_Entry` chunk-mezőire (`chunkIndex`/`chunkTotal`)
+ * normalizálja, és a **tiny-file fallback**-et alkalmazza (ha egyetlen stratégia sem ad chunkot
+ * VAGY a fájl a `chunk.fallbackWholeFileUnder` alatt van → 1 db `chunkType='fallback'` chunk, hogy
+ * semmi ne essen ki, dsgn-004 §3.4).
+ *
+ * Singleton (a config-resolve / dispatch állapot-mentes; az egységes belépés a hot-path-nak).
+ */
+class FAM_Chunker_ControlService {
+    static _instance;
+    static getInstance() {
+        if (!FAM_Chunker_ControlService._instance) {
+            FAM_Chunker_ControlService._instance = new FAM_Chunker_ControlService();
+        }
+        return FAM_Chunker_ControlService._instance;
+    }
+    /**
+     * Egy fájl tartalmának chunkolása a route + kiterjesztés szerinti stratégiával (dsgn-004 §3). A
+     * méret-konstansok a config-ból (`table`+`scopePath` kontextusra) feloldva; a tiny-fallback a
+     * `chunk.fallbackWholeFileUnder` alatt VAGY üres-chunklista esetén. A `chunkIndex`/`chunkTotal` a
+     * teljes batch-re konzisztens (a delta-kulcshoz, SP-4.3).
+     */
+    async chunkFile(set) {
+        const strategy = fam_file_routing_util_1.FAM_FileRouting_Util.chunkStrategyFor(set.relativePath);
+        const fallbackUnder = await this.resolveNumber('chunk.fallbackWholeFileUnder', set.table, set.scopePath, 50);
+        // Tiny-file fallback (a `fallbackWholeFileUnder` alatt → 1 chunk, dsgn-004 §3.4).
+        if (set.content.trim().length > 0 && set.content.length < fallbackUnder) {
+            return [this.fallbackChunk(set.content)];
+        }
+        const sizing = await this.resolveSizing(strategy, set.table, set.scopePath);
+        const rawChunks = this.runStrategy(strategy, set.content, sizing);
+        // Üres-chunklista de NEM üres tartalom → tiny-fallback (semmi ne essen ki).
+        if (!rawChunks.length) {
+            if (!set.content.trim().length) {
+                return [];
+            }
+            return [this.fallbackChunk(set.content)];
+        }
+        return this.assignIndices(rawChunks);
+    }
+    /** A stratégia futtatása (TS / MD / generic). */
+    runStrategy(strategy, content, sizing) {
+        if (strategy === 'ts') {
+            return fam_ts_chunker_util_1.FAM_TsChunker_Util.chunkText(content, sizing);
+        }
+        if (strategy === 'md') {
+            return fam_md_chunker_util_1.FAM_MdChunker_Util.chunkText(content, sizing);
+        }
+        return fam_sliding_chunker_util_1.FAM_SlidingChunker_Util.chunkText(content, sizing);
+    }
+    /** A teljes tartalom egyetlen `fallback`-chunkként (tiny-file fallback, dsgn-004 §3.4). */
+    fallbackChunk(content) {
+        const trimmed = content.trim();
+        return {
+            content: trimmed,
+            chunkIndex: 0,
+            chunkTotal: 1,
+            chunkType: 'fallback',
+            position: { charStart: 0, charEnd: content.length },
+            headingPath: [],
+        };
+    }
+    /** A nyers chunkokra a 0-alapú `chunkIndex` + a közös `chunkTotal` (a delta-kulcshoz). */
+    assignIndices(rawChunks) {
+        const total = rawChunks.length;
+        return rawChunks.map((raw, index) => ({
+            content: raw.content,
+            chunkIndex: index,
+            chunkTotal: total,
+            chunkType: raw.chunkType,
+            position: raw.position,
+            headingPath: raw.headingPath,
+        }));
+    }
+    /** A stratégia méret-konstansai a config-ból (default a CCAP-érték, dsgn-007 §4.2). */
+    async resolveSizing(strategy, table, scopePath) {
+        if (strategy === 'ts') {
+            return {
+                maxSize: await this.resolveNumber('chunk.ts.maxSize', table, scopePath, 1500),
+                overlap: await this.resolveNumber('chunk.ts.overlap', table, scopePath, 100),
+                minSize: await this.resolveNumber('chunk.ts.minSize', table, scopePath, 50),
+            };
+        }
+        if (strategy === 'md') {
+            return {
+                maxSize: await this.resolveNumber('chunk.md.maxSize', table, scopePath, 1200),
+                overlap: await this.resolveNumber('chunk.md.overlap', table, scopePath, 150),
+                minSize: await this.resolveNumber('chunk.md.minSize', table, scopePath, 80),
+            };
+        }
+        return {
+            maxSize: await this.resolveNumber('chunk.generic.maxSize', table, scopePath, 1200),
+            overlap: await this.resolveNumber('chunk.generic.overlap', table, scopePath, 150),
+            minSize: await this.resolveNumber('chunk.generic.minSize', table, scopePath, 50),
+        };
+    }
+    /** Egy numerikus config-kulcs feloldása (table+scope kontextus); nem-szám → a builtin fallback. */
+    async resolveNumber(key, table, scopePath, fallback) {
+        const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve(key, { table: table, scopePath: scopePath });
+        return typeof resolved.value === 'number' ? resolved.value : fallback;
+    }
+}
+exports.FAM_Chunker_ControlService = FAM_Chunker_ControlService;