@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/ingest/_services/fam-delta-compare.util.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_DeltaCompare_Util = void 0;
+const fam_content_hash_util_1 = require("../_collections/fam-content-hash.util");
+/**
+ * `FAM_DeltaCompare_Util` (SP-4.3, dsgn-004 §4, **BFR-AM-006 workaround**) — az idempotens
+ * delta-detection. A `(sourceFilePath, chunkIndex)` kulcs + `contentHash` alapján veti össze az ÚJ
+ * batch chunkjait a táron MÁR meglévő (nem soft-deleted) chunkokkal, és `equal | modified | new |
+ * deleted` verdiktet ad (dsgn-004 §4.2):
+ *
+ * - `new`      : a `(fájl, index)` kulcs még nem volt a táron → insert új embeddinggel.
+ * - `equal`    : a kulcs létezik ÉS a `contentHash` egyezik → **skip** (NINCS re-embed — ez az
+ *                embedding-költség fő minimalizálója).
+ * - `modified` : a kulcs létezik, de a `contentHash` eltér → re-embed + `$set`.
+ * - `deleted`  : a táron volt chunk, amit az új batch MÁR NEM tartalmaz (a fájl rövidült/törölt)
+ *                → soft-delete (a `chunk` ekkor `null`, az `existingId` a soft-deletelendő `_id`).
+ *
+ * **BFR-AM-006 (dsgn-004 §4 megjegyzés):** a CCAP `RAG_DataCompare_Util.compareData` (deep-equal a
+ * nem-metadata mezőkön) generikus alternatíva; MVP1-ben a contentHash-alapú összevetés elég (a
+ * `content` a vektorizálandó kanonikus szöveg, így a hash dönt). MEGJEGYZÉS: a `DyNTS_DataService`
+ * base mostanra (`nts-dynamo@1.15.57`) shippeli a generikus `compareData(new, old, options?)`-t —
+ * a BFR-AM-006 bedrock-oldala TEHÁT MÁR ELÉRHETŐ; ám a delta-detection szándékosan a
+ * contentHash-kulcson marad (a chunk-azonosság a `(fájl, index)` kulcs + a normalizált
+ * tartalom-hash, NEM a mező-szintű deep-equal — ez a dsgn-004 §4.1 szerinti SSOT). Statikus util.
+ */
+class FAM_DeltaCompare_Util {
+    /**
+     * A delta-verdiktek egy fájl ÚJ chunk-batch-ére (dsgn-004 §4.2). Az `existing` a táron meglévő
+     * (nem soft-deleted) `FAM_Entry`-k az adott `sourceFilePath`-ra; a kulcs a `chunkIndex`. A
+     * batch után minden olyan `existing` kulcs, amire NINCS új chunk → `deleted`.
+     *
+     * A `contentHash`-t a util itt számolja az ÚJ chunkokra (`FAM_ContentHash_Util.hash`,
+     * normalizált) — az `existing.contentHash` a táron tárolt érték.
+     */
+    static compare(newChunks, existing) {
+        const existingByIndex = new Map();
+        for (const entry of existing) {
+            if (typeof entry.chunkIndex === 'number') {
+                existingByIndex.set(entry.chunkIndex, entry);
+            }
+        }
+        const items = [];
+        const matchedIndices = new Set();
+        // (1) Az új chunkok verdiktje (new / equal / modified).
+        for (const chunk of newChunks) {
+            const contentHash = fam_content_hash_util_1.FAM_ContentHash_Util.hash(chunk.content);
+            const existingEntry = existingByIndex.get(chunk.chunkIndex);
+            if (!existingEntry) {
+                items.push({ verdict: 'new', chunk: chunk, contentHash: contentHash });
+                continue;
+            }
+            matchedIndices.add(chunk.chunkIndex);
+            if (existingEntry.contentHash === contentHash) {
+                items.push({ verdict: 'equal', chunk: chunk, existingId: existingEntry._id, contentHash: contentHash });
+            }
+            else {
+                items.push({ verdict: 'modified', chunk: chunk, existingId: existingEntry._id, contentHash: contentHash });
+            }
+        }
+        // (2) A táron maradt, az új batch-ben NEM szereplő kulcsok → deleted (a fájl rövidült/törölt).
+        for (const entry of existing) {
+            if (typeof entry.chunkIndex === 'number' && !matchedIndices.has(entry.chunkIndex)) {
+                items.push({
+                    verdict: 'deleted',
+                    chunk: null,
+                    existingId: entry._id,
+                    contentHash: entry.contentHash ?? '',
+                });
+            }
+        }
+        return items;
+    }
+}
+exports.FAM_DeltaCompare_Util = FAM_DeltaCompare_Util;

package/build/src/_modules/ingest/_services/fam-ingest-run.data-service.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_IngestRun_DataService = void 0;
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const fam_ingest_run_data_model_1 = require("../../../_models/data-models/fam-ingest-run.data-model");
+/**
+ * `FAM_IngestRun_DataService` (SP-4.4, dsgn-001 §7 / dsgn-004 §5) — a `fam_ingest_runs` (MAIN)
+ * collection CRUD-ja. `extends DyNTS_DataService` (a `dataParams.addArchive=true` — soft-delete a
+ * `getArchiveDataService`-en át, move-to-archive). Minden scan-művelet EGYETLEN run-rekordot ír; a
+ * rekord a scan ELEJÉN nyílik (`open`), a VÉGÉN záródik (`close`).
+ *
+ * **Mongoose Mixed atomic-write (memory: reference_mongoose_mixed_atomic_write):** a `verdicts` /
+ * `errors` / `scopePath` Mixed-szerű mezők `findOne→mutate→save`-vel SILENT-DROP-ot adhatnak —
+ * ezért a run-FRISSÍTÉS `updateOne({_id},{$set:{...}})` úton megy (`close`), NEM olvasás-mutáció-
+ * mentés. A nyitó `open` egy fresh `saveData` (új rekord), ami safe.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** a base-ctor EAGER `getDBService`-t hív,
+ * ezért a control-service-ek NEM tartanak élő példányt mezőként — minden művelet előtt lazy `new`.
+ */
+class FAM_IngestRun_DataService extends nts_dynamo_1.DyNTS_DataService {
+    constructor(set) {
+        super(set.data instanceof fam_ingest_run_data_model_1.FAM_IngestRun_DataModel ? set.data : new fam_ingest_run_data_model_1.FAM_IngestRun_DataModel(set.data), fam_ingest_run_data_model_1.famIngestRun_dataParams, set.issuer);
+    }
+    /**
+     * A move-to-archive soft-delete (dsgn-001 §8) archív-collection service-e: a base `deleteData`
+     * (addArchive) ezt hívja, hogy a törölt run-rekordot a `fam_ingest_runs_archived` tárba mozgassa. A
+     * `DyNTS_DataService` base default-ja DOB (nincs ökoszisztéma-implementáció) — ezért az explicit
+     * override (a `DyNTS_ArchiveDataService` a `dataParams.addArchive`-ból oldja az archív-nevet).
+     */
+    getArchiveDataService() {
+        return new nts_dynamo_1.DyNTS_ArchiveDataService(new fam_ingest_run_data_model_1.FAM_IngestRun_DataModel(), this.dataParams, this.issuer);
+    }
+    /**
+     * A run megnyitása a scan ELEJÉN (dsgn-004 §5). A `_id` = a hívó által generált runId (UUID v4),
+     * hogy a chunkok az `ingestRunId`-vel HIVATKOZHASSANAK rá MÉG a run-zárás előtt. Friss `saveData`
+     * (új rekord — nincs Mixed-mutáció). A számlálók/verdiktek a `close`-ban frissülnek.
+     */
+    async open(set) {
+        const record = new fam_ingest_run_data_model_1.FAM_IngestRun_DataModel({
+            _id: set.runId,
+            trigger: set.trigger,
+            table: set.table,
+            scopePath: set.scopePath,
+            rootPath: set.rootPath,
+            filesProcessed: 0,
+            filesSkipped: 0,
+            chunkCount: 0,
+            verdicts: { new: 0, modified: 0, equal: 0, deleted: 0 },
+            status: 'ok',
+            errors: [],
+        });
+        return this.saveData(record);
+    }
+    /**
+     * A run lezárása a scan VÉGÉN (dsgn-004 §5) — atomikus `$set` (Mixed silent-drop ellen). A
+     * `verdicts` / `errors` / a számlálók / `status` / `durationMs` / opc. `table`-bővítés egy
+     * lépésben. NEM olvasás-mutáció-mentés.
+     */
+    async close(set) {
+        const setBlock = {
+            table: set.table,
+            filesProcessed: set.filesProcessed,
+            filesSkipped: set.filesSkipped,
+            chunkCount: set.chunkCount,
+            verdicts: set.verdicts,
+            durationMs: set.durationMs,
+            status: set.status,
+            errors: set.errors,
+        };
+        if (set.embedTokenCost !== undefined) {
+            setBlock.embedTokenCost = set.embedTokenCost;
+        }
+        const update = { $set: setBlock };
+        await this.updateData({ filterBy: { _id: set.runId }, update: update });
+    }
+    /** Egy run a `_id` alapján (vagy üres-objektum, ha nincs). */
+    async findRunById(runId) {
+        return this.findData({ _id: runId }, true);
+    }
+    /** A run-ok lapozatlan listája (legutóbbiak felül; a `list_scan_runs` capability, MP-6 fogyasztja). */
+    async listRuns(filter) {
+        return this.findDataList(filter ?? {}, true);
+    }
+}
+exports.FAM_IngestRun_DataService = FAM_IngestRun_DataService;

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

@@ -0,0 +1,384 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Ingest_ControlService = void 0;
+const tslib_1 = require("tslib");
+const crypto = tslib_1.__importStar(require("crypto"));
+const fs = tslib_1.__importStar(require("fs"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const errors_control_service_1 = require("../../../_routes/server/errors/errors.control-service");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const fam_entry_data_model_1 = require("../../../_models/data-models/fam-entry.data-model");
+const embedding_1 = require("../../embedding");
+const scope_reference_1 = require("../../scope-reference");
+const fam_chunker_control_service_1 = require("./fam-chunker.control-service");
+const fam_delta_compare_util_1 = require("./fam-delta-compare.util");
+const fam_ingest_run_data_service_1 = require("./fam-ingest-run.data-service");
+const fam_scan_control_service_1 = require("./fam-scan.control-service");
+/**
+ * `FAM_Ingest_ControlService` (SP-4.4, dsgn-004 §1/§4/§5) — az ingest-orchestrátor. A teljes
+ * `write(scan-*)` pipeline EGY belépési ponton:
+ *
+ * `scan*` → scope reference-resolve (MP-3) → fájl-felderítés + routing (SP-4.1) → per-fájl chunk
+ * (SP-4.2) → delta-detection (SP-4.3) → embed CSAK a `new`/`modified`-re (MP-2 `embedAndPersist`) →
+ * persist (`addedBy='scan'`, `ingestRunId`, canonical `scopePath`) → `deleted` soft-delete →
+ * `FAM_IngestRun` összefoglaló + `famIngest` MON-esemény (dsgn-004 §5).
+ *
+ * **Idempotencia (dsgn-004 §8.4):** ugyanazt a forrást kétszer scan-elve a 2. futás minden chunkja
+ * `equal` → 0 `new`/`modified` → 0 embedding-hívás (a `embedAndPersist` CSAK a `new`/`modified`-re fut).
+ *
+ * **Részleges hiba (dsgn-004 §8.9, no-silent-failure):** egy fájl chunking-/embedding-hibája NEM
+ * buktatja az egész run-t — a hiba `errors[]`-be (a központi error-rétegen, MP-8), a `status`
+ * `partial-failed`-re emelve, a többi fájl feldolgozva. A scope-resolve hibája viszont a scan ELŐTT
+ * bukik (a run `failed`, NINCS fájl-bejárás).
+ *
+ * Singleton (memory: dynts_dataservice_eager_resolve — NEM tartunk élő DataService-mezőt).
+ */
+class FAM_Ingest_ControlService {
+    static _instance;
+    /** Default issuer az ingest-műveletekhez. */
+    issuer = 'FAM_Ingest_ControlService';
+    static getInstance() {
+        if (!FAM_Ingest_ControlService._instance) {
+            FAM_Ingest_ControlService._instance = new FAM_Ingest_ControlService();
+        }
+        return FAM_Ingest_ControlService._instance;
+    }
+    // =========================================================================
+    // Belépési pontok (a `write` MCP-eszköz / REST — MP-6 — ezeket hívja)
+    // =========================================================================
+    /** `scan-file` (dsgn-004 §1) — egyetlen fájl re-ingestje. */
+    async scanFile(request) {
+        return this.runScan({ ...request, operation: 'scan-file' });
+    }
+    /** `scan-folder` (dsgn-004 §1) — egy mappa (rekurzív) fájljainak ingestje. */
+    async scanFolder(request) {
+        return this.runScan({ ...request, operation: 'scan-folder' });
+    }
+    /** `scan-project` (dsgn-004 §1) — a teljes projekt-korpusz egyetlen művelettel. */
+    async scanProject(request) {
+        return this.runScan({ ...request, operation: 'scan-project' });
+    }
+    // =========================================================================
+    // Group-by-run + group-delete (SP-4.4, dsgn-004 §5; `list_scan_runs` capability — MP-6)
+    // =========================================================================
+    /**
+     * Egy futtatás összes (nem soft-deleted) chunkja minden fő tárból (dsgn-004 §5 csoport-megjelenítés).
+     * A `list_scan_runs` → run-chunks capability (MP-6) ezt fogyasztja. A `FAM_STORE_REGISTRY` minden
+     * fő táron lekérdez az `ingestRunId`-re (egy scan-project több tárat is érinthet).
+     */
+    async listRunChunks(ingestRunId) {
+        const result = [];
+        for (const registryEntry of embedding_1.FAM_STORE_REGISTRY) {
+            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+            const filter = { ingestRunId: ingestRunId };
+            const chunks = await dataService.findHydratableList(filter);
+            result.push(...chunks);
+        }
+        return result;
+    }
+    /**
+     * Egy futtatás összes chunkjának csoportos SOFT-delete-je minden fő tárból (dsgn-004 §5
+     * delete-run capability — MP-6 maintenance). A törölt chunkok NEM retrieve-elődnek (MP-5). A run
+     * rekordot maga NEM törli (audit-history megmarad). Visszaadja a törölt chunkok számát.
+     */
+    async deleteRun(ingestRunId) {
+        let deleted = 0;
+        for (const registryEntry of embedding_1.FAM_STORE_REGISTRY) {
+            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+            const chunks = await dataService.findHydratableList({ ingestRunId: ingestRunId });
+            for (const chunk of chunks) {
+                if (chunk._id) {
+                    await dataService.deleteData(chunk._id);
+                    deleted++;
+                }
+            }
+        }
+        return deleted;
+    }
+    // =========================================================================
+    // Az ingest-pipeline mag (SP-4.4)
+    // =========================================================================
+    /**
+     * A teljes scan-pipeline (dsgn-004 §1). A scope KÖTELEZŐ reference-resolve-on megy át (MP-3); a
+     * resolve-hiba → a run `failed` (NINCS fájl-bejárás). A felderítés + per-fájl feldolgozás után a
+     * run lezárul a verdict-aggregátummal + `status`-szal; a MON-esemény kibocsátódik.
+     */
+    async runScan(request) {
+        const issuer = request.issuer ?? this.issuer;
+        const runId = crypto.randomUUID();
+        const startedAt = Date.now();
+        // (1) Scope reference-resolve (MP-3 `resolveForWrite`) — KÖTELEZŐ. Hiba → run `failed`.
+        let canonicalScope;
+        try {
+            const resolved = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().resolveForWrite(this.toRawScope(request.scopePath));
+            canonicalScope = resolved.scopePath;
+        }
+        catch (error) {
+            // A scope feloldatlan → a run NEM futott le. A scope-hiba MÁR persistált (MP-3 emitálja);
+            // itt csak a `failed` run-summary-t adjuk vissza (a hívó deskriptív blokkot kap).
+            return this.failedSummary({
+                runId: runId, request: request, startedAt: startedAt,
+                error: error, scopePath: [],
+            });
+        }
+        // (2) Fájl-felderítés + routing + security (SP-4.1).
+        let discovery;
+        try {
+            discovery = await fam_scan_control_service_1.FAM_Scan_ControlService.getInstance().discover({
+                operation: request.operation,
+                path: request.path,
+                scopePath: canonicalScope,
+                include: request.include,
+                exclude: request.exclude,
+                tableOverride: request.tableOverride,
+            });
+        }
+        catch (error) {
+            return this.failedSummary({
+                runId: runId, request: request, startedAt: startedAt,
+                error: error, scopePath: canonicalScope,
+            });
+        }
+        // (3) A run megnyitása (a chunkok ezzel az `ingestRunId`-vel hivatkoznak rá).
+        const runDataService = new fam_ingest_run_data_service_1.FAM_IngestRun_DataService({ issuer: issuer });
+        await runDataService.open({
+            runId: runId,
+            trigger: request.operation,
+            table: discovery.tables,
+            scopePath: canonicalScope,
+            rootPath: request.path,
+        });
+        // (4) Per-fájl feldolgozás (flow-limit kötegekben; a per-fájl hiba NEM buktatja a run-t).
+        const verdicts = { new: 0, modified: 0, equal: 0, deleted: 0 };
+        const errors = [];
+        let chunkCount = 0;
+        const flowLimit = await this.resolveFlowLimit(canonicalScope);
+        for (let i = 0; i < discovery.routedFiles.length; i += flowLimit) {
+            const batch = discovery.routedFiles.slice(i, i + flowLimit);
+            const results = await Promise.all(batch.map((file) => this.processFile({
+                file: file, runId: runId, scopePath: canonicalScope,
+                dryRun: request.dryRun ?? false, issuer: issuer, errors: errors,
+            })));
+            for (const result of results) {
+                if (!result) {
+                    continue;
+                }
+                chunkCount += result.chunkCount;
+                this.tallyVerdicts(verdicts, result.deltaItems);
+            }
+        }
+        // (5) A run lezárása (atomikus `$set`) + MON-esemény.
+        const status = errors.length ? 'partial-failed' : 'ok';
+        const durationMs = Date.now() - startedAt;
+        await runDataService.close({
+            runId: runId, table: discovery.tables,
+            filesProcessed: discovery.routedFiles.length, filesSkipped: discovery.skippedFiles.length,
+            chunkCount: chunkCount, verdicts: verdicts, durationMs: durationMs, status: status, errors: errors,
+        });
+        const summary = {
+            ingestRunId: runId, trigger: request.operation, table: discovery.tables,
+            scopePath: canonicalScope, rootPath: request.path,
+            filesProcessed: discovery.routedFiles.length, filesSkipped: discovery.skippedFiles.length,
+            chunkCount: chunkCount, verdicts: verdicts, durationMs: durationMs, status: status, errors: errors,
+        };
+        this.emitMonEvent(summary);
+        return summary;
+    }
+    /**
+     * Egy route-olt fájl feldolgozása (dsgn-004 §3/§4): olvasás → chunk (SP-4.2) → delta (SP-4.3) →
+     * akció-routing a verdikt szerint (`equal`→skip, `new`/`modified`→embed+persist, `deleted`→
+     * soft-delete). A per-fájl hiba `errors[]`-be (no-silent-failure) + `null` visszatérés (a run nem bukik).
+     */
+    async processFile(set) {
+        const table = set.file.route;
+        try {
+            const content = fs.readFileSync(set.file.absolutePath, 'utf-8');
+            const chunks = await fam_chunker_control_service_1.FAM_Chunker_ControlService.getInstance().chunkFile({
+                content: content, relativePath: set.file.relativePath, table: table, scopePath: set.scopePath,
+            });
+            const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(table);
+            if (!registryEntry) {
+                throw new Error(`No store-registry entry for table '${table}'.`);
+            }
+            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: set.issuer });
+            // Existing-by-key betöltés (a fájl nem soft-deleted chunkjai, scope-szűkítve).
+            const existing = await this.loadExistingChunks(dataService, set.file.relativePath, set.scopePath);
+            const deltaItems = fam_delta_compare_util_1.FAM_DeltaCompare_Util.compare(chunks, existing);
+            if (!set.dryRun) {
+                await this.applyVerdicts({
+                    deltaItems: deltaItems, file: set.file, table: table, runId: set.runId,
+                    scopePath: set.scopePath, dataService: dataService,
+                });
+            }
+            return {
+                file: set.file,
+                deltaItems: deltaItems,
+                chunkCount: chunks.length,
+                fallbackUsed: chunks.length === 1 && chunks[0].chunkType === 'fallback',
+            };
+        }
+        catch (error) {
+            // No-silent-failure: a per-fájl hibát persistáljuk + az `errors[]`-be tesszük (a run
+            // `partial-failed`-re emelkedik, a többi fájl feldolgozva — dsgn-004 §8.9).
+            const famError = await errors_control_service_1.FAM_Error_ControlService.getInstance().emit({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.scanRead,
+                message: `A fájl feldolgozása sikertelen a scan során: '${set.file.relativePath}'. A run a többi `
+                    + 'fájllal folytatódik (partial-failed).',
+                cause: error,
+                context: {
+                    operation: 'ingest-process-file', runId: set.runId,
+                    sourceFilePath: set.file.relativePath, table: table,
+                },
+            });
+            set.errors.push({
+                errorCode: fsm_dynamo_1.DyFM_Error.getErrorCode(famError),
+                message: fsm_dynamo_1.DyFM_Error.getErrorMessage(famError),
+                sourceFilePath: set.file.relativePath,
+            });
+            return null;
+        }
+    }
+    /**
+     * Az akció-routing a delta-verdiktek szerint (dsgn-004 §4.2): `equal` → skip (NINCS re-embed);
+     * `new` → insert + embed; `modified` → re-embed + `$set`; `deleted` → soft-delete. Az embed CSAK
+     * a `new`/`modified`-re fut (MP-2 `embedAndPersist`) — ez az embedding-költség fő minimalizálója.
+     */
+    async applyVerdicts(set) {
+        for (const item of set.deltaItems) {
+            if (item.verdict === 'equal') {
+                continue;
+            }
+            if (item.verdict === 'deleted') {
+                if (item.existingId) {
+                    await set.dataService.deleteData(item.existingId);
+                }
+                continue;
+            }
+            // new / modified → upsert + embed (a `chunk` itt sosem null).
+            if (item.chunk) {
+                await this.persistAndEmbed({
+                    chunk: item.chunk, existingId: item.existingId, contentHash: item.contentHash,
+                    file: set.file, table: set.table, runId: set.runId, scopePath: set.scopePath,
+                    dataService: set.dataService,
+                });
+            }
+        }
+    }
+    /**
+     * Egy `new`/`modified` chunk persistálása + embeddelése (dsgn-004 §4.2 + dsgn-006 §3). A
+     * `FAM_Entry` a chunk-mezőkkel + scope + `ingestRunId` + `addedBy='scan'` + `source` provenance;
+     * a mentés UTÁN a MP-2 `embedAndPersist` vektorizál (CSAK itt — az `equal`-eken NEM).
+     */
+    async persistAndEmbed(set) {
+        const entry = new fam_entry_data_model_1.FAM_Entry({
+            _id: set.existingId,
+            table: set.table,
+            content: set.chunk.content,
+            contentHash: set.contentHash,
+            embeddingStatus: 'pending',
+            scopePath: set.scopePath,
+            sourceFilePath: set.file.relativePath,
+            chunkIndex: set.chunk.chunkIndex,
+            chunkTotal: set.chunk.chunkTotal,
+            chunkType: set.chunk.chunkType,
+            position: set.chunk.position,
+            headingPath: set.chunk.headingPath,
+            source: { type: 'scan', path: set.file.relativePath },
+            addedBy: 'scan',
+            ingestRunId: set.runId,
+        });
+        // Persist (saveData = upsert: meglévő `_id` → modify, hiányzó → insert).
+        const saved = await set.dataService.saveData(entry);
+        // Embed CSAK a new/modified-re (MP-2). Az embed-hiba az entry-t `error`-státuszba teszi +
+        // persistál (a `embedAndPersist` belül kezeli, no-silent-failure) — NEM dob ide.
+        await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().embedAndPersist({
+            table: set.table, entry: saved, callType: 'embed-write',
+        });
+    }
+    // =========================================================================
+    // helpers
+    // =========================================================================
+    /**
+     * A fájl meglévő (nem soft-deleted) chunkjai a táron + scope-on belül (`Map`-elésre a delta-
+     * kulcshoz, SP-4.3). A `findHydratableList` az aktívakat adja (a soft-delete-elteket kihagyja).
+     * A scope-szűkítés a LEVÉL scopeId-jára (a write-path canonical scopePath-ot ír az entry-re).
+     */
+    async loadExistingChunks(dataService, sourceFilePath, scopePath) {
+        const filter = { sourceFilePath: sourceFilePath };
+        if (scopePath.length) {
+            const leaf = scopePath[scopePath.length - 1];
+            filter['scopePath.scopeId'] = leaf.scopeId;
+        }
+        return dataService.findHydratableList(filter);
+    }
+    /** A verdikt-számok aggregálása a `FAM_IngestRun.verdicts`-be. */
+    tallyVerdicts(verdicts, items) {
+        for (const item of items) {
+            verdicts[item.verdict]++;
+        }
+    }
+    /** A nyers `FAM_RawScopeLayer[]` a request scope-jából (a MP-3 `resolveForWrite` bemenete). */
+    toRawScope(scopePath) {
+        return scopePath;
+    }
+    /** A párhuzamos fájl-feldolgozás flow-limitje a config-ból (`ingest.flowLimit`, default 20, cap 200). */
+    async resolveFlowLimit(scopePath) {
+        const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('ingest.flowLimit', { scopePath: scopePath });
+        const value = typeof resolved.value === 'number' ? resolved.value : 20;
+        return Math.min(Math.max(value, 1), 200);
+    }
+    /**
+     * A `failed` run-summary (a scope-resolve / felderítés bukásakor). A run rekord-mentés best-effort
+     * (a hiba MÁR persistált); a hívónak a `failed` summary jelzi, hogy a scan nem futott le.
+     */
+    async failedSummary(set) {
+        const errorEntry = { message: set.error?.message ?? 'scan failed before file walk' };
+        const summary = {
+            ingestRunId: set.runId, trigger: set.request.operation, table: [],
+            scopePath: set.scopePath, rootPath: set.request.path,
+            filesProcessed: 0, filesSkipped: 0, chunkCount: 0,
+            verdicts: { new: 0, modified: 0, equal: 0, deleted: 0 },
+            durationMs: Date.now() - set.startedAt, status: 'failed', errors: [errorEntry],
+        };
+        try {
+            const runDataService = new fam_ingest_run_data_service_1.FAM_IngestRun_DataService({ issuer: this.issuer });
+            await runDataService.open({
+                runId: set.runId, trigger: set.request.operation, table: [],
+                scopePath: set.scopePath, rootPath: set.request.path,
+            });
+            await runDataService.close({
+                runId: set.runId, table: [], filesProcessed: 0, filesSkipped: 0, chunkCount: 0,
+                verdicts: summary.verdicts, durationMs: summary.durationMs, status: 'failed', errors: summary.errors,
+            });
+        }
+        catch (persistError) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM ingest] a failed-run rekord mentése sikertelen (runId=${set.runId}): `
+                + `${persistError?.message}`);
+        }
+        this.emitMonEvent(summary);
+        return summary;
+    }
+    /**
+     * A `famIngest` MON-esemény a run végén (dsgn-004 §5; a CCAP `ragIngest` általánosítva). MVP1: a
+     * `DyFM_Log.info`-n strukturált payload-dal (a MP-8/MP-10 Logs-modul + idővonal-wiring KÉSŐBBI MP;
+     * a Logs-routing még nincs installálva az App-ban — ezt NEM rántjuk előre). A payload shape a
+     * dsgn-004 §5 szerinti (event/ingestRunId/trigger/table/verdicts/durationMs/status).
+     */
+    emitMonEvent(summary) {
+        fsm_dynamo_1.DyFM_Log.info('[famIngest]', {
+            event: 'famIngest',
+            ingestRunId: summary.ingestRunId,
+            trigger: summary.trigger,
+            table: summary.table,
+            scopePath: summary.scopePath.map((ref) => ref.canonicalName).join('>'),
+            filesProcessed: summary.filesProcessed,
+            filesSkipped: summary.filesSkipped,
+            chunkCount: summary.chunkCount,
+            verdicts: summary.verdicts,
+            durationMs: summary.durationMs,
+            status: summary.status,
+        });
+    }
+}
+exports.FAM_Ingest_ControlService = FAM_Ingest_ControlService;