@futdevpro/fdp-agent-memory 1.1.21 → 1.1.112

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

@@ -0,0 +1,429 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScanJob_ControlService = void 0;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const fam_cooldown_util_1 = require("../../../_collections/fam-cooldown.util");
+const fam_operation_queue_service_1 = require("../../../_collections/fam-operation-queue.service");
+const fam_scan_progress_sink_service_1 = require("../../../_collections/fam-scan-progress-sink.service");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const fam_write_tool_service_1 = require("../../mcp/_services/fam-write-tool.service");
+const fam_mcp_interface_1 = require("../../mcp/_models/interfaces/fam-mcp.interface");
+const fam_project_discovery_util_1 = require("../../../_collections/fam-project-discovery.util");
+const fam_scan_job_data_service_1 = require("./fam-scan-job.data-service");
+const fam_scan_job_data_model_1 = require("../../../_models/data-models/fam-scan-job.data-model");
+/**
+ * `FAM_ScanJob_ControlService` (FEAT-008 Phase 2) — **szerver-oldali async multi-projekt scan-orchestráció**. A user-
+ * direktíva: a SZERVER vezényelje a teljes scant (felderítés + soros feldolgozás + cooldown + queue + progress), NE a
+ * CLI. A `start` AZONNAL visszaadja a `jobId`-t (nincs hosszú request → nincs Node-requestTimeout), a feldolgozás
+ * háttérben fut: projektenként a meglévő `FAM_WriteTool_Service.handle()` (scan-project) az `FAM_OperationQueue_Service`
+ * queue-n át (szerializáció), majd FELTÉTELES szerver-cooldown (≥`cooldownMinChunks` embed → `cooldownMs` várás). Az
+ * állapot in-memory (single-server, single-user) — a `getStatus` poll-ozható. Statikus singleton.
+ */
+class FAM_ScanJob_ControlService {
+    static instance;
+    static getInstance() {
+        if (!FAM_ScanJob_ControlService.instance) {
+            FAM_ScanJob_ControlService.instance = new FAM_ScanJob_ControlService();
+        }
+        return FAM_ScanJob_ControlService.instance;
+    }
+    issuer = 'FAM_ScanJob_ControlService';
+    /** Stall-küszöb default (ms), ha a config nem oldódott fel (FEAT-008 Phase 5) — 2 perc. */
+    static DEFAULT_STALL_THRESHOLD_MS = 120000;
+    /** Az aktív + befejezett job-ok (in-memory; a server-restart eldobja — followup: Mongo-perzisztencia). */
+    jobs = new Map();
+    /** Per-job feloldott stall-küszöb (ms) — a `start`/`resume` resolve-olja, a `getStatus` poll sync-ben olvassa. */
+    stallThresholdMsByJob = new Map();
+    /** Teszt-override a per-projekt futtatóra (a default valós scan-t indít a queue-n át). */
+    scanRunnerOverride;
+    /** TESZT-only: a per-projekt scan-futtató cseréje (valós Mongo/embedding nélkül). */
+    setScanRunnerForTest(runner) {
+        this.scanRunnerOverride = runner;
+    }
+    /** TESZT-only: a singleton + állapot eldobása. */
+    static resetForTest() {
+        FAM_ScanJob_ControlService.instance = undefined;
+    }
+    /**
+     * Egy scan-job INDÍTÁSA. Feloldja a projekt-listát (explicit `projects` VAGY `root`-felderítés), létrehozza a
+     * job-ot, ELINDÍTJA a háttér-feldolgozást (fire-and-forget), és AZONNAL visszaadja a `jobId`-t + a `total`-t.
+     * Üres lista → `Error` (a hívó 400-at ad). A cooldown a configból oldódik fel (override-olható a bemenetből).
+     */
+    async start(input) {
+        const specs = FAM_ScanJob_ControlService.resolveSpecs(input);
+        if (specs.length === 0) {
+            throw new Error('Nincs feldolgozandó projekt (üres `projects`/`configPath` és a `root`-felderítés sem adott találatot).');
+        }
+        const cooldownMs = input.cooldownMs !== undefined
+            ? Math.max(0, Math.floor(input.cooldownMs))
+            : await FAM_ScanJob_ControlService.resolveConfigNumber('scan.projectCooldownMs', 10000);
+        const cooldownMinChunks = input.cooldownMinChunks !== undefined
+            ? Math.max(0, Math.floor(input.cooldownMinChunks))
+            : await FAM_ScanJob_ControlService.resolveConfigNumber('scan.projectCooldownMinChunks', 100);
+        const now = Date.now();
+        const job = {
+            jobId: (0, crypto_1.randomUUID)(),
+            status: 'pending',
+            total: specs.length,
+            currentIndex: 0,
+            okCount: 0,
+            cooldownMs: cooldownMs,
+            cooldownMinChunks: cooldownMinChunks,
+            startedAt: now,
+            lastProgressAt: now,
+            resumeCount: 0,
+            // KI indította (user-FR 2026-06-25): a beazonosíthatósághoz a job-on rögzítjük a hívó aláírását.
+            origin: input.origin,
+            projects: specs.map((spec) => ({
+                project: spec.project, path: spec.path, status: 'pending',
+            })),
+            cancelRequested: false,
+        };
+        this.jobs.set(job.jobId, job);
+        // Stall-küszöb feloldása (FEAT-008 Phase 5) — in-memory tárolva, hogy a sync `getStatus` poll olvashassa.
+        this.stallThresholdMsByJob.set(job.jobId, await FAM_ScanJob_ControlService.resolveConfigNumber('scan.stallThresholdMs', FAM_ScanJob_ControlService.DEFAULT_STALL_THRESHOLD_MS));
+        // DURABLE perzisztencia (FEAT-008 Phase 4): a job + a specs + a per-projekt állapot Mongo-ba → túléli a
+        // server-restart/crash/close-t, és a szerver AUTO-RESUME-olja a megszakítási ponttól. Best-effort (a perzisztencia
+        // hibája NE buktassa a scant — a futás in-memory akkor is megy).
+        await this.persistCreate(job, specs, input.sourceLocation);
+        // Fire-and-forget: a feldolgozás háttérben fut (a request NEM várja meg → nincs requestTimeout).
+        void this.process(job, specs).catch((error) => {
+            job.status = 'failed';
+            job.finishedAt = Date.now();
+            job.failureReason = `feldolgozás összeomlott: ${error?.message ?? 'ismeretlen'}`;
+            void this.persistUpdate(job);
+            fsm_dynamo_1.DyFM_Log.warn(`[scanJob ${job.jobId}] ${job.failureReason}`);
+        });
+        fsm_dynamo_1.DyFM_Log.info(`[scanJob ${job.jobId}] indítva: ${specs.length} projekt, cooldown ${cooldownMs}ms `
+            + `(ha ≥${cooldownMinChunks} embed chunk)`);
+        // Fast-path (user-FR 2026-06-22): a `start` legfeljebb `waitMs`-ig (default 15s) megvárja a befejezést — ha
+        // a job ennyin belül kész, a TELJES eredményt adjuk vissza AZONNAL (nincs külön poll-hívás); különben a futó
+        // job-ot (`jobId` + `running` + ETA) → a hívó poll-oz. `0` = ne várj.
+        const waitMs = input.waitMs !== undefined ? Math.max(0, Math.floor(input.waitMs)) : 15000;
+        await FAM_ScanJob_ControlService.awaitTerminalOrTimeout(job, waitMs);
+        return this.withEta(job);
+    }
+    /** A job befejezésének (vagy a `waitMs` lejártának) megvárása — a fast-path szinkron eredményéhez. */
+    static async awaitTerminalOrTimeout(job, waitMs) {
+        if (waitMs <= 0) {
+            return;
+        }
+        const deadline = Date.now() + waitMs;
+        while (Date.now() < deadline) {
+            if (job.status === 'completed' || job.status === 'failed' || job.status === 'cancelled') {
+                return;
+            }
+            await fam_cooldown_util_1.FAM_Cooldown_Util.sleep(100);
+        }
+    }
+    /** Egy job állapota (poll). `undefined`, ha ismeretlen (a hívó 404-et ad). Az ETA + stall frissítve. */
+    getStatus(jobId) {
+        const job = this.jobs.get(jobId);
+        return job ? this.withEta(job) : undefined;
+    }
+    /**
+     * AZ ÖSSZES (futó + befejezett) job KOMPAKT összefoglalója (FEAT-008 Phase 5) — legfrissebb ELŐL. Így egy elárvult/
+     * futó job a `jobId` ismerete NÉLKÜL is felfedezhető (a user kérdése: „fut egyáltalán valami?"). A stall-jelzés is benne.
+     */
+    listJobs() {
+        return Array.from(this.jobs.values())
+            .map((job) => this.withEta(job))
+            .sort((a, b) => b.startedAt - a.startedAt)
+            .map((job) => ({
+            jobId: job.jobId, status: job.status, total: job.total, okCount: job.okCount,
+            currentIndex: job.currentIndex, startedAt: job.startedAt, finishedAt: job.finishedAt,
+            etaSeconds: job.etaSeconds, stalled: job.stalled, stalledForSeconds: job.stalledForSeconds,
+            origin: job.origin,
+        }));
+    }
+    /** A job ETA + within-project sub-progress + STALL-jelzés frissítése (mutál + visszaad). Csak futó job-on értelmes. */
+    withEta(job) {
+        job.etaSeconds = FAM_ScanJob_ControlService.computeEtaSeconds(job);
+        const live = fam_scan_progress_sink_service_1.FAM_ScanProgress_Sink.get();
+        if (job.status === 'running') {
+            job.currentProgress = live
+                ? { scopeLabel: live.scopeLabel, processed: live.processed, total: live.total, pct: live.pct, chunkCount: live.chunkCount }
+                : undefined;
+        }
+        else {
+            job.currentProgress = undefined;
+        }
+        // STALL: a per-target `lastProgressAt` ÉS a within-target progress-sink `updatedAt` közül a frissebbhez mérjük a
+        // tétlenséget. A küszöb a job indításakor feloldott `scan.stallThresholdMs` (in-memory, sync-elérhető a poll-on).
+        const stall = FAM_ScanJob_ControlService.computeStall({
+            status: job.status,
+            lastProgressAt: job.lastProgressAt ?? job.startedAt,
+            sinkUpdatedAt: (job.status === 'running' && live) ? live.updatedAt : undefined,
+            nowMs: Date.now(),
+            thresholdMs: this.stallThresholdMsByJob.get(job.jobId) ?? FAM_ScanJob_ControlService.DEFAULT_STALL_THRESHOLD_MS,
+        });
+        job.stalled = stall.stalled;
+        job.stalledForSeconds = stall.stalledForSeconds;
+        return job;
+    }
+    /**
+     * A STALL determinisztikus számítása (pure, tesztelhető — nincs Date.now/config). CSAK `running` job-on: a `nowMs` és
+     * a LEGFRISSEBB haladás-jel (`max(lastProgressAt, sinkUpdatedAt)`) különbsége. `stalled=true`, ha ez ≥ `thresholdMs`.
+     * A `stalledForSeconds` mindig a tétlenség (futó job-on); terminál/`thresholdMs<=0` → nincs stall.
+     */
+    static computeStall(set) {
+        if (set.status !== 'running') {
+            return { stalled: false, stalledForSeconds: undefined };
+        }
+        const freshest = Math.max(set.lastProgressAt, set.sinkUpdatedAt ?? 0);
+        const idleMs = Math.max(0, set.nowMs - freshest);
+        const stalled = set.thresholdMs > 0 && idleMs >= set.thresholdMs;
+        return { stalled: stalled, stalledForSeconds: Math.round(idleMs / 1000) };
+    }
+    /**
+     * A becsült hátralévő idő (mp) — pure. CSAK futó job-on értelmes: a már (ok/error) kész projektek átlag-ideje ×
+     * a hátralévő projektek száma. `undefined`, ha terminál, vagy ha még semmi sem készült el (nincs mérés).
+     */
+    static computeEtaSeconds(job) {
+        if (job.status === 'completed' || job.status === 'failed' || job.status === 'cancelled') {
+            return undefined;
+        }
+        const done = job.projects.filter((project) => project.status === 'ok' || project.status === 'error');
+        if (done.length === 0) {
+            return undefined;
+        }
+        const elapsedSeconds = (Date.now() - job.startedAt) / 1000;
+        const remaining = job.total - done.length;
+        return Math.max(0, Math.round((elapsedSeconds / done.length) * remaining));
+    }
+    /** Megszakítás-kérés: a processor a következő projekt ELŐTT ellenőrzi. `true`, ha a job létezett + futott. */
+    cancel(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.status === 'completed' || job.status === 'failed' || job.status === 'cancelled') {
+            return false;
+        }
+        job.cancelRequested = true;
+        return true;
+    }
+    /** A háttér-feldolgozás: soros projekt-loop a queue-n át + feltételes szerver-cooldown. */
+    async process(job, specs) {
+        job.status = 'running';
+        const runner = this.scanRunnerOverride ?? ((spec) => this.defaultRunProject(spec));
+        for (let index = 0; index < specs.length; index++) {
+            if (job.cancelRequested) {
+                job.status = 'cancelled';
+                job.finishedAt = Date.now();
+                job.failureReason = `felhasználói megszakítás a(z) ${index + 1}/${specs.length} projektnél`;
+                await this.persistUpdate(job);
+                fsm_dynamo_1.DyFM_Log.info(`[scanJob ${job.jobId}] ${job.failureReason}`);
+                return;
+            }
+            // RESUME (FEAT-008 Phase 4): a már `ok` projekteket ÁTUGORJUK (a megszakítási ponttól folytatunk —
+            // nem scan-eljük újra, amit egy korábbi futás befejezett). Az `error`/`pending`/`running` újrafut.
+            if (job.projects[index].status === 'ok') {
+                continue;
+            }
+            job.currentIndex = index;
+            job.projects[index].status = 'running';
+            job.lastProgressAt = Date.now(); // egy projekt feldolgozásának KEZDETE is haladás (a stall-óra resetelődik)
+            // Per-projekt PROGRESS a process-logba (user-FR 2026-06-25 — „hanyadik projektből hányadikon járunk"): a
+            // detached FAM-ablakot figyelve egyből látszik a pozíció (`[12/48] <projekt>`), nem kell a REST-et poll-ozni.
+            fsm_dynamo_1.DyFM_Log.info(`[scanJob ${job.jobId}] [${index + 1}/${specs.length}] ${specs[index].project} — feldolgozás…`);
+            const result = await runner(specs[index]);
+            job.projects[index] = result;
+            job.lastProgressAt = Date.now(); // per-target BEFEJEZÉS → friss haladás-jel a stall-detekciónak
+            if (result.status === 'ok') {
+                job.okCount++;
+            }
+            // Per-projekt CHECKPOINT (durable) — a job állapota minden projekt után Mongo-ba, hogy a resume innen folytasson.
+            await this.persistUpdate(job);
+            // Feltételes szerver-cooldown (FEAT-008): a projektek KÖZÉ (nem az utolsó után) CSAK ha az előző projekt
+            // ≥ cooldownMinChunks valódi embed-munkát végzett — `equal`-csak projekt után nincs gép-terhelés.
+            const embedded = result.embedded ?? 0;
+            if (FAM_ScanJob_ControlService.shouldCooldown({
+                embedded: embedded, minChunks: job.cooldownMinChunks, cooldownMs: job.cooldownMs,
+                isLast: index === specs.length - 1,
+            })) {
+                fsm_dynamo_1.DyFM_Log.info(`[scanJob ${job.jobId}] cooldown ${job.cooldownMs}ms (${embedded} chunk embed-elve) — `
+                    + `${index + 1}/${specs.length} kész`);
+                await fam_cooldown_util_1.FAM_Cooldown_Util.sleep(job.cooldownMs);
+            }
+        }
+        job.currentIndex = specs.length;
+        job.status = 'completed';
+        job.finishedAt = Date.now();
+        await this.persistUpdate(job);
+        fsm_dynamo_1.DyFM_Log.info(`[scanJob ${job.jobId}] KÉSZ: ${job.okCount}/${specs.length} ok`);
+    }
+    /** A job durable rekordjának LÉTREHOZÁSA (best-effort — a perzisztencia hibája nem buktatja a scant). */
+    async persistCreate(job, specs, sourceLocation) {
+        try {
+            await new fam_scan_job_data_service_1.FAM_ScanJob_DataService({ issuer: this.issuer }).createJob(new fam_scan_job_data_model_1.FAM_ScanJob_DataModel({
+                jobId: job.jobId, status: job.status, total: job.total, currentIndex: job.currentIndex,
+                okCount: job.okCount, cooldownMs: job.cooldownMs, cooldownMinChunks: job.cooldownMinChunks,
+                startedAt: job.startedAt, projects: job.projects, specs: specs, sourceLocation: sourceLocation,
+                resumeCount: job.resumeCount ?? 0,
+            }));
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[scanJob ${job.jobId}] durable-create sikertelen (a scan in-memory folytatódik): ${error?.message}`);
+        }
+    }
+    /** A job durable rekordjának FRISSÍTÉSE (atomikus $set, per-projekt checkpoint) — best-effort. */
+    async persistUpdate(job) {
+        try {
+            await new fam_scan_job_data_service_1.FAM_ScanJob_DataService({ issuer: this.issuer }).updateJobByJobId(job.jobId, {
+                status: job.status, currentIndex: job.currentIndex, okCount: job.okCount,
+                projects: job.projects, finishedAt: job.finishedAt,
+                resumeCount: job.resumeCount, failureReason: job.failureReason,
+            });
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[scanJob ${job.jobId}] durable-update sikertelen: ${error?.message}`);
+        }
+    }
+    /**
+     * AUTO-RESUME (FEAT-008 Phase 4, user-FR 2026-06-22) — a startup-on (a bootstrap hidratálás után) hívva: a Mongo-ban
+     * `running`/`pending`-en ragadt (megszakadt) job-okat folytatja a megszakítási ponttól (a már `ok` projekteket a
+     * `process` átugorja). Best-effort. A visszaadott szám = hány job-ot indított újra.
+     */
+    async resumeInterrupted() {
+        let resumed = 0;
+        try {
+            const dataService = new fam_scan_job_data_service_1.FAM_ScanJob_DataService({ issuer: this.issuer });
+            const maxResumeCount = await FAM_ScanJob_ControlService.resolveConfigNumber('scan.maxResumeCount', 5);
+            const stallThresholdMs = await FAM_ScanJob_ControlService.resolveConfigNumber('scan.stallThresholdMs', FAM_ScanJob_ControlService.DEFAULT_STALL_THRESHOLD_MS);
+            const docs = await dataService.findResumable();
+            for (const doc of docs) {
+                if (!doc.jobId || !Array.isArray(doc.specs) || doc.specs.length === 0) {
+                    continue;
+                }
+                // RESUME-CAP (FEAT-008 Phase 5): egy folyton-elakadó job ne induljon újra a végtelenségig minden restartkor.
+                // A cap elérésekor a durable rekordot `failed`-re zárjuk (failureReason) — így a `findResumable` többé nem hozza.
+                const priorResumes = doc.resumeCount ?? 0;
+                if (maxResumeCount <= 0 || priorResumes >= maxResumeCount) {
+                    const reason = `resume-cap túllépve (${priorResumes}/${maxResumeCount}) — nem indítjuk újra automatikusan`;
+                    await dataService.updateJobByJobId(doc.jobId, { status: 'failed', finishedAt: Date.now(), failureReason: reason });
+                    fsm_dynamo_1.DyFM_Log.warn(`[scanJob ${doc.jobId}] ${reason}`);
+                    continue;
+                }
+                const now = Date.now();
+                const job = {
+                    jobId: doc.jobId, status: 'running', total: doc.total ?? doc.specs.length,
+                    currentIndex: doc.currentIndex ?? 0, okCount: doc.okCount ?? 0,
+                    cooldownMs: doc.cooldownMs ?? 0, cooldownMinChunks: doc.cooldownMinChunks ?? 100,
+                    startedAt: doc.startedAt ?? now,
+                    lastProgressAt: now, // a resume pillanata friss haladás-jel (a stall-óra innen indul)
+                    resumeCount: priorResumes + 1,
+                    cancelRequested: false,
+                    projects: doc.projects ?? doc.specs.map((spec) => ({ project: spec.project, path: spec.path, status: 'pending' })),
+                };
+                this.jobs.set(job.jobId, job);
+                this.stallThresholdMsByJob.set(job.jobId, stallThresholdMs);
+                // A megnövelt resumeCount-ot AZONNAL persistáljuk (ha ez a resume is megszakad, a következő boot a magasabb
+                // számról indul → a cap konvergál; különben egy crash-loop sosem érné el a capet).
+                await dataService.updateJobByJobId(job.jobId, { resumeCount: job.resumeCount });
+                const doneCount = job.projects.filter((project) => project.status === 'ok').length;
+                fsm_dynamo_1.DyFM_Log.info(`[scanJob ${job.jobId}] RESUME (${job.resumeCount}/${maxResumeCount}): ${doneCount}/${job.total} kész — folytatás a megszakítási ponttól`);
+                void this.process(job, doc.specs).catch((error) => {
+                    job.status = 'failed';
+                    job.finishedAt = Date.now();
+                    job.failureReason = `resume-feldolgozás összeomlott: ${error?.message ?? 'ismeretlen'}`;
+                    void this.persistUpdate(job);
+                    fsm_dynamo_1.DyFM_Log.warn(`[scanJob ${job.jobId}] ${job.failureReason}`);
+                });
+                resumed++;
+            }
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[scanJob] resume-keresés sikertelen: ${error?.message}`);
+        }
+        return resumed;
+    }
+    /** A default per-projekt futtató: a meglévő `scan-project` write-handler az operation-queue-n át. */
+    async defaultRunProject(spec) {
+        const startedAt = Date.now();
+        // Per-target scope: az EXPLICIT `spec.scopePath` nyer (heterogén „scan-all"-hoz, pl. a memóriám root-szintű
+        // scope-ja); különben a default `[organization=org, project=project]`.
+        const scopePath = (spec.scopePath && spec.scopePath.length)
+            ? spec.scopePath
+            : [
+                { layer: 'organization', rawName: spec.org ?? 'FutDevPro' },
+                { layer: 'project', rawName: spec.project },
+            ];
+        const input = {
+            table: spec.table ?? fam_table_type_enum_1.FAM_Table.codebase,
+            operation: fam_mcp_interface_1.FAM_WriteOperation.scanProject,
+            scopePath: scopePath,
+            scan: {
+                path: spec.path,
+                preserveHistory: spec.preserveHistory,
+                tableOverride: spec.tableOverride ? spec.tableOverride : undefined,
+                include: spec.include,
+                exclude: spec.exclude,
+            },
+        };
+        try {
+            const output = await fam_operation_queue_service_1.FAM_OperationQueue_Service.getInstance()
+                .enqueue(() => fam_write_tool_service_1.FAM_WriteTool_Service.getInstance().handle(input));
+            const scan = output.scan;
+            const verdicts = scan?.verdicts;
+            return {
+                project: spec.project, path: spec.path, status: 'ok',
+                filesProcessed: scan?.filesProcessed, chunks: scan?.chunks, verdicts: verdicts,
+                embedded: verdicts ? verdicts.new + verdicts.modified : 0,
+                seconds: Math.round((Date.now() - startedAt) / 1000),
+            };
+        }
+        catch (error) {
+            return {
+                project: spec.project, path: spec.path, status: 'error',
+                seconds: Math.round((Date.now() - startedAt) / 1000),
+                error: { message: error?.message ?? 'ismeretlen scan-hiba' },
+            };
+        }
+    }
+    /**
+     * A feltételes cooldown DÖNTÉSE (pure, tesztelhető): a projektek KÖZÉ vár, ha cooldown be van kapcsolva
+     * (`cooldownMs>0`), NEM az utolsó projekt után (`!isLast`), ÉS az előző projekt ≥ `minChunks`-ot embeddelt.
+     */
+    static shouldCooldown(set) {
+        return set.cooldownMs > 0 && !set.isLast && set.embedded >= set.minChunks;
+    }
+    /**
+     * A projekt-lista feloldása: explicit `projects` > `configPath` (a szerver olvassa) > `root`-felderítés. A relatív
+     * útvonalak a HÍVÓ `sourceLocation`-jéhez oldódnak fel (a szerver cwd-je eltér a CLI-étől — user-FR 2026-06-22):
+     * a `configPath`/`root` ÉS a végső per-projekt `path` is.
+     */
+    static resolveSpecs(input) {
+        const base = (target) => (target && input.sourceLocation && !(0, path_1.isAbsolute)(target)) ? (0, path_1.resolve)(input.sourceLocation, target) : target;
+        let specs = [];
+        if (input.projects && input.projects.length > 0) {
+            specs = input.projects;
+        }
+        else if (input.configPath) {
+            specs = fam_project_discovery_util_1.FAM_ProjectDiscovery_Util.parseConfig((0, fs_1.readFileSync)(base(input.configPath) ?? input.configPath, 'utf-8'));
+        }
+        else if (input.root) {
+            specs = fam_project_discovery_util_1.FAM_ProjectDiscovery_Util.discover(base(input.root) ?? input.root, input.depth ?? 3, { org: input.org, table: input.table });
+        }
+        // „scan-all": az EXTRA célok (pl. a memóriám additív szkenje) a feloldott lista UTÁN (akkor is, ha a fő lista üres).
+        if (input.extraTargets && input.extraTargets.length) {
+            specs = [...specs, ...input.extraTargets];
+        }
+        // A per-projekt `path` relatív → a sourceLocation-höz feloldva (a discover már abszolútat ad; a config relatív lehet).
+        return specs.map((spec) => ({ ...spec, path: base(spec.path) ?? spec.path }));
+    }
+    /** Egy szám-config feloldása (a hiba/hiány a fallback-ra esik — a cooldown sosem buktatja a job-ot). */
+    static async resolveConfigNumber(key, fallback) {
+        try {
+            const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve(key, {});
+            const value = resolved.value;
+            const num = typeof value === 'number' ? value : Number(value);
+            return Number.isFinite(num) && num >= 0 ? Math.floor(num) : fallback;
+        }
+        catch {
+            return fallback;
+        }
+    }
+}
+exports.FAM_ScanJob_ControlService = FAM_ScanJob_ControlService;

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

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScanJob_DataService = void 0;
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const fam_scan_job_data_model_1 = require("../../../_models/data-models/fam-scan-job.data-model");
+/**
+ * `FAM_ScanJob_DataService` (FEAT-008 Phase 4) — a `fam_scan_jobs` collection CRUD-ja a DURABLE scan-job-okhoz.
+ * A job a `start`-kor nyílik (`createJob`, friss `saveData`), és per-projekt FRISSÜL (`updateJobByJobId`, atomikus
+ * `$set` — a Mixed-szerű `projects[]`/`specs[]` ne dropoljon silent-en `findOne→mutate→save`-vel). A resume a
+ * `findResumable`-lel keresi a megszakadt (`running`/`pending`) job-okat. `extends DyNTS_DataService` (addArchive).
+ */
+class FAM_ScanJob_DataService extends nts_dynamo_1.DyNTS_DataService {
+    constructor(set) {
+        super(set.data instanceof fam_scan_job_data_model_1.FAM_ScanJob_DataModel ? set.data : new fam_scan_job_data_model_1.FAM_ScanJob_DataModel(set.data), fam_scan_job_data_model_1.famScanJob_dataParams, set.issuer);
+    }
+    /** A move-to-archive soft-delete archív-service-e (a base `deleteData` ezt hívja; addArchive). */
+    getArchiveDataService() {
+        return new nts_dynamo_1.DyNTS_ArchiveDataService(new fam_scan_job_data_model_1.FAM_ScanJob_DataModel(), this.dataParams, this.issuer);
+    }
+    /** Egy ÚJ job durable rekordja (friss `saveData` — nincs Mixed-mutáció). */
+    async createJob(model) {
+        return this.saveData(model);
+    }
+    /** Egy job FRISSÍTÉSE a `jobId` alapján — atomikus `$set` (Mixed silent-drop ellen; per-projekt checkpoint). */
+    async updateJobByJobId(jobId, setBlock) {
+        const update = { $set: setBlock };
+        await this.updateData({ filterBy: { jobId: jobId }, update: update });
+    }
+    /** A megszakadt (resume-olandó) job-ok: `status ∈ {running, pending}`. A startup-resume ezeket folytatja. */
+    async findResumable() {
+        return this.findDataList({ status: { $in: ['running', 'pending'] } }, true);
+    }
+}
+exports.FAM_ScanJob_DataService = FAM_ScanJob_DataService;

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

@@ -266,15 +266,17 @@ class FAM_Scan_ControlService {
         return Array.from(tables);
     }
     /**
-     * Az effektív ignore-patterns: a config `scan.ignorePatterns` (default `SCAN_IGNORE_PATTERNS_DEFAULT`)
-     * + az input `exclude` HOZZÁADVA (dsgn-004 §6.2 — a `write.scan.exclude` HOZZÁADÓDIK, NEM felülír).
+     * Az effektív ignore-patterns. **SAFETY-FLOOR (2026-06-22):** a `SCAN_IGNORE_PATTERNS_DEFAULT` MINDIG
+     * érvényesül — a build/dist/.local-state/secrets-féle junk + személyes-adat SOSE eshet ki egy config-
+     * override-tól (ez volt a footgun: a régi config `scan.ignorePatterns` REPLACE-elte a defaultot). A config
+     * `scan.ignorePatterns` + az input `exclude` ezen FELÜL HOZZÁADÓDIK (dsgn-004 §6.2). Dedup-olt union.
      */
     async resolveIgnorePatterns(scopePath, exclude) {
         const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('scan.ignorePatterns', { scopePath: scopePath });
         const configPatterns = Array.isArray(resolved.value)
             ? resolved.value.filter((item) => typeof item === 'string')
-            : config_catalog_const_1.SCAN_IGNORE_PATTERNS_DEFAULT;
-        return [...configPatterns, ...(exclude ?? [])];
+            : [];
+        return [...new Set([...config_catalog_const_1.SCAN_IGNORE_PATTERNS_DEFAULT, ...configPatterns, ...(exclude ?? [])])];
     }
     /** A méret-plafon a config-ból (`scan.maxFileSizeBytes`, default 1 MB). */
     async resolveMaxFileSize(scopePath) {

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

@@ -12,7 +12,7 @@
  * (MVP1 csak fájlnév-/útvonal-alapú secret-exclude).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_IngestRun_DataService = exports.FAM_ContentHash_Util = exports.FAM_DeltaCompare_Util = exports.FAM_SlidingChunker_Util = exports.FAM_MdChunker_Util = exports.FAM_TsChunker_Util = exports.FAM_Chunker_ControlService = exports.FAM_GlobMatch_Util = exports.FAM_SecretExclude_Util = exports.FAM_ScanPath_Util = exports.FAM_ScanProgress_Util = exports.FAM_FileRouting_Util = exports.FAM_Scan_ControlService = exports.FAM_Ingest_ControlService = void 0;
+exports.FAM_IngestRun_DataService = exports.FAM_ContentHash_Util = exports.FAM_DeltaCompare_Util = exports.FAM_SplitChunker_Util = exports.FAM_Frontmatter_Util = exports.FAM_SlidingChunker_Util = exports.FAM_MdChunker_Util = exports.FAM_TsChunker_Util = exports.FAM_Chunker_ControlService = exports.FAM_GlobMatch_Util = exports.FAM_SecretExclude_Util = exports.FAM_ScanPath_Util = exports.FAM_ScanProgress_Util = exports.FAM_FileRouting_Util = exports.FAM_Scan_ControlService = exports.FAM_Ingest_ControlService = void 0;
 // SP-4.4 — ingest-orchestrátor (a `write(scan-*)` belépési pontja + group-by-run/delete-run)
 var fam_ingest_control_service_1 = require("./_services/fam-ingest.control-service");
 Object.defineProperty(exports, "FAM_Ingest_ControlService", { enumerable: true, get: function () { return fam_ingest_control_service_1.FAM_Ingest_ControlService; } });
@@ -38,6 +38,11 @@ var fam_md_chunker_util_1 = require("./_collections/fam-md-chunker.util");
 Object.defineProperty(exports, "FAM_MdChunker_Util", { enumerable: true, get: function () { return fam_md_chunker_util_1.FAM_MdChunker_Util; } });
 var fam_sliding_chunker_util_1 = require("./_collections/fam-sliding-chunker.util");
 Object.defineProperty(exports, "FAM_SlidingChunker_Util", { enumerable: true, get: function () { return fam_sliding_chunker_util_1.FAM_SlidingChunker_Util; } });
+// Rules-Management MP-3 — fájl-fej frontmatter (F-A) + strukturális split-chunker (F-B)
+var fam_frontmatter_util_1 = require("./_collections/fam-frontmatter.util");
+Object.defineProperty(exports, "FAM_Frontmatter_Util", { enumerable: true, get: function () { return fam_frontmatter_util_1.FAM_Frontmatter_Util; } });
+var fam_split_chunker_util_1 = require("./_collections/fam-split-chunker.util");
+Object.defineProperty(exports, "FAM_SplitChunker_Util", { enumerable: true, get: function () { return fam_split_chunker_util_1.FAM_SplitChunker_Util; } });
 // SP-4.3 — idempotens delta-detection
 var fam_delta_compare_util_1 = require("./_services/fam-delta-compare.util");
 Object.defineProperty(exports, "FAM_DeltaCompare_Util", { enumerable: true, get: function () { return fam_delta_compare_util_1.FAM_DeltaCompare_Util; } });

package/build/src/_modules/mcp/_collections/fam-core-tools.const.js

@@ -25,7 +25,7 @@ const MAIN_TABLE_ENUM = Object.values(fam_table_type_enum_1.FAM_Table).filter((t
 /** A nyers scope-lánc array-schema (`{ layer, rawName }[]`). */
 const SCOPE_LAYER_ARRAY = {
     type: 'array',
-    description: 'Nyers scope-lánc (root→leaf): [{ layer, rawName }] párok (pl. organization=FutDevPro, project=Adventor).',
+    description: 'Nyers scope-lánc (root→leaf): [{ layer: layer, rawName: rawName }] párok (pl. organization=FutDevPro, project=Adventor).',
     items: {
         type: 'object',
         properties: {