@futdevpro/fdp-agent-memory 1.1.30 → 1.1.113

package/build/src/_collections/fam-entry-bootstrap.util.js

@@ -9,6 +9,7 @@ const app_server_1 = require("../app.server");
 const package_json_1 = require("../../package.json");
 const mcp_1 = require("../_modules/mcp");
 const fam_client_service_1 = require("../_cli/_services/fam-client.service");
+const serve_command_1 = require("../_cli/_commands/serve.command");
 const register_commands_1 = require("../_cli/register-commands");
 const fam_console_util_1 = require("./fam-console.util");
 const fam_mcp_bridge_util_1 = require("./fam-mcp-bridge.util");
@@ -92,6 +93,23 @@ class FAM_EntryBootstrap_Util {
             fsm_dynamo_1.DyFM_Log.warn(`[FAM] már fut egy egészséges FAM-primary (${client.getBaseUrl()}${versionTag}) — a második REST-boot kihagyva.${versionNote}`);
             return;
         }
+        if (isStart && !serverAlreadyRunning) {
+            // AUTO-ENSURE (user-FR 2026-06-22: „minden fam funkciónak gondoskodnia kell a fam elindításáról"). Az MCP-
+            // stdio process NE a heavy REST-primary-t bootolja IN-PROCESS (az OOM-nál MEGHAL → a Claude-reconnect crash-
+            // loop-ol), hanem húzzon fel egy LEVÁLASZTOTT primary-t (túléli a reconnectet) és BRIDGE-eljen hozzá. A
+            // `waitMs:1` csak a spawn-t INDÍTJA (nem várja a teljes pool-bootot) → az MCP-handshake (ListTools, ami nem
+            // igényli a primary-t) AZONNAL kész; a tool-CALL-ok a bridge-önhealen várnak/retry-znek a boot-ra.
+            const ensured = await serve_command_1.FAM_Serve_Util.ensureRunning({ waitMs: 1 });
+            const spawnUnavailable = ensured.reason === 'no-entry' || ensured.reason === 'spawn-failed' || ensured.reason === 'remote-unreachable';
+            if (!spawnUnavailable) {
+                fsm_dynamo_1.DyFM_Log.info(`[FAM] auto-ensure: leválasztott primary (${ensured.reason}, ${ensured.url}) → MCP-stdio BRIDGE `
+                    + '(a primary a háttérben bootol; a tool-hívások önhealnek).');
+                await fam_mcp_bridge_util_1.FAM_McpBridge_Util.start({ name: MCP_SERVER_NAME, version: package_json_1.version });
+                return;
+            }
+            // A leválasztott spawn nem indítható (nincs belépő / spawn-hiba / remote-URL) → VISSZA a bevált in-process PRIMARY-ra.
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM] auto-ensure: a leválasztott primary nem indítható (${ensured.reason}) → in-process PRIMARY boot (fallback).`);
+        }
         // PRIMARY-jelölt (nincs egészséges futó primary). Port pre-flight: ha a portot MÁS tartja (egy nem-FAM
         // process, VAGY egy fél-halott FAM-szerver, ami már nem válaszol a `/api/health`-en), a kötés EADDRINUSE-
         // szal bukna egy nyers stack-kel. Ehelyett TISZTA, akcióképes hibát adunk és kilépünk (nem crashelünk).
@@ -105,14 +123,10 @@ class FAM_EntryBootstrap_Util {
         }
         // PRIMARY (nincs futó szerver, a port szabad) — a teljes szerver felhúzása.
         fsm_dynamo_1.DyFM_Log.info(`[FAM] PRIMARY mód: nincs futó FAM-primary → teljes szerver felhúzása (REST :${SERVER_PORT}`
-            + `${isStart ? ' + MCP stdio' : ''}). Activity-monitor: ${fam_console_util_1.FAM_Console_Util.isEnabled() ? 'ON' : 'OFF'}`
-            + `${fam_console_util_1.FAM_Console_Util.isEnabled() ? ` (${fam_console_util_1.FAM_Console_Util.isVerbose() ? 'VERBOSE — minden log' : 'kurált'})` : ''}.`);
+            + `${isStart ? ' + MCP stdio' : ''}).`);
         // File-log (FAM_LOG_FILE): a `fam serve` ezt állítja be → a detached szerver logjai (köztük az
-        // import-progress) FÁJLBÓL OLVASHATÓK (tail), a monitor-ablak nélkül is. Fail-safe, env-gated.
+        // import-progress) FÁJLBÓL OLVASHATÓK (tail) a látható szerver-ablak MELLETT. Fail-safe, env-gated.
         fam_console_util_1.FAM_Console_Util.installFileLog();
-        // (FEAT-001) A PRIMARY egy KÜLÖN, látható activity-konzol-ablakot nyit (env-gated, fail-safe,
-        // docker-ben OFF). Az MCP-stdio JSON-RPC csatornát NEM érinti (külön monitor-process tail-el).
-        fam_console_util_1.FAM_Console_Util.openActivityConsole({ port: SERVER_PORT });
         // (1) REST szerver felhúzása (a DyNTS_App ctor indítja a connect + setup + postProcess láncot;
         // a DyNTS_App a side-effect-konstruktor mintát követi — az `index.ts` is így indít).
         FAM_EntryBootstrap_Util.startRestApp();

package/build/src/_collections/fam-error-context.util.js

@@ -37,6 +37,7 @@ class FAM_ErrorContext_Util {
         FAM_ErrorContext_Util.setNumber(snapshot, 'chunkIndex', input.chunkIndex);
         FAM_ErrorContext_Util.setString(snapshot, 'query', input.query);
         FAM_ErrorContext_Util.setString(snapshot, 'provider', input.provider);
+        FAM_ErrorContext_Util.setString(snapshot, 'failedSample', input.failedSample);
         // Ha minden mező hiányzott, NINCS snapshot (a rekordon nem jelenik meg üres objektum).
         return Object.keys(snapshot).length ? snapshot : undefined;
     }

package/build/src/_collections/fam-mcp-bridge.util.js

@@ -4,6 +4,7 @@ exports.FAM_McpBridge_Util = void 0;
 const fam_core_tools_const_1 = require("../_modules/mcp/_collections/fam-core-tools.const");
 const fam_mcp_adapter_service_1 = require("../_modules/mcp/_services/fam-mcp-adapter.service");
 const fam_client_service_1 = require("../_cli/_services/fam-client.service");
+const serve_command_1 = require("../_cli/_commands/serve.command");
 /**
  * `FAM_McpBridge_Util` (FEAT-002, topology „egy szerver, sok bridge") — ha `fam start`-kor MÁR fut egy
  * FAM-szerver (primary, REST a 39265-ön), az új process NEM bootol második szervert (port-ütközés +
@@ -31,7 +32,20 @@ class FAM_McpBridge_Util {
                 description: tool.description,
                 inputSchema: tool.inputSchema,
                 handler: async (args) => {
-                    const result = await client.post(`/api/${tool.name}`, args ?? {});
+                    let result = await client.post(`/api/${tool.name}`, args ?? {});
+                    // ÖNHEAL (user-FR 2026-06-22): ha a primary időközben leesett (`unreachable`), NE bukjunk némán —
+                    // automatikusan felhúzzuk a leválasztott primary-t (`ensureRunning`) és EGYSZER újrapróbáljuk. Ha a
+                    // primary épp bootol (pool-hidratálás), tiszta „indul, próbáld újra" hibát adunk (a következő hívás megy).
+                    if (!result.ok && result.unreachable) {
+                        const ensured = await serve_command_1.FAM_Serve_Util.ensureRunning();
+                        if (ensured.running) {
+                            result = await client.post(`/api/${tool.name}`, args ?? {});
+                        }
+                        else if (ensured.reason === 'boot-timeout') {
+                            throw new Error('FAM-MCP-BRIDGE-002: A FAM primary most indul (pool-hidratálás folyamatban) — '
+                                + 'próbáld újra pár másodperc múlva. (Az auto-indítás már elindult, leválasztva.)');
+                        }
+                    }
                     if (!result.ok) {
                         // A primary hibáját MCP-hibaként felszínre hozzuk (NEM némítjuk; dsgn-008).
                         const code = result.error?.errorCode ?? 'FAM-MCP-BRIDGE-001';

package/build/src/_collections/fam-operation-queue.service.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_OperationQueue_Service = void 0;
+/**
+ * `FAM_OperationQueue_Service` (FEAT-008, user-FR 2026-06-22) — **szerver-oldali soros/limitált-konkurrencia QUEUE**
+ * a NEHÉZ műveletekhez (scan/import/re-embed). A user-direktíva: a SZERVER vezérelje, hogy egyszerre NE fusson túl
+ * sok nehéz művelet — ha több agenttől egyidejű write-parancsok érkeznek, a szerver SORBA rakja (FIFO) és úgy
+ * dolgozza fel, NEM párhuzamosan. (Ez okozta a `war-factory`/`warbots` átfedést: a kliens-oldali orchestráció
+ * desync-elt — a kliens timeout-olt egy hosszú scant és elindította a következőt, miközben a szerver az elsőt még
+ * darálta. Ezzel a queue-val a 2. write MEGVÁRJA az elsőt → soros, átfedés-mentes feldolgozás a kliens-káosztól
+ * függetlenül.)
+ *
+ * Egyszerű async-szemafór: `maxConcurrency` default **1** (teljes szerializáció a nehéz ops-ra). A könnyű ops
+ * (create/update/delete/read) NEM mennek ezen át (gyorsak, nincs korrupciós kockázat). Statikus singleton —
+ * process-szintű (egy szerver = egy queue). Bukott task is felszabadít (finally) → nem akad meg a queue.
+ */
+class FAM_OperationQueue_Service {
+    /** A process-szintű singleton. */
+    static instance;
+    /** A singleton elérése (lazy). */
+    static getInstance() {
+        if (!FAM_OperationQueue_Service.instance) {
+            FAM_OperationQueue_Service.instance = new FAM_OperationQueue_Service();
+        }
+        return FAM_OperationQueue_Service.instance;
+    }
+    /** A konkurrencia-plafon (≥1). Default 1 = teljes szerializáció (egyszerre egy nehéz művelet). */
+    maxConcurrency = 1;
+    /** Hány task fut épp. */
+    running = 0;
+    /** A szabad slot-ra várók resolver-ei (FIFO sor). */
+    waiters = [];
+    /** A konkurrencia-plafon állítása (≥1). Növelésnél azonnal besorolja a várakozókat. */
+    setMaxConcurrency(value) {
+        this.maxConcurrency = Math.max(1, Math.floor(value));
+        this.drain();
+    }
+    /** Observability (a `/health`-be / progress-be köthető): hány fut + hány vár + a plafon. */
+    stats() {
+        return { running: this.running, queued: this.waiters.length, maxConcurrency: this.maxConcurrency };
+    }
+    /**
+     * A `task` BESOROLÁSA: megvárja a szabad slot-ot (FIFO), lefuttatja, majd felszabadít. A hiba is felszabadít
+     * (`finally`) — egy bukott task NEM akasztja meg a queue-t. A visszatérés a task eredménye (átlátszó wrapper).
+     */
+    async enqueue(task) {
+        await this.acquire();
+        try {
+            return await task();
+        }
+        finally {
+            this.release();
+        }
+    }
+    /** Slot-foglalás: ha van szabad → azonnal; különben FIFO-sorba (a resolver a `drain`-ben fut le). */
+    acquire() {
+        if (this.running < this.maxConcurrency) {
+            this.running++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    /** Slot-felszabadítás + a következő várakozó besorolása. */
+    release() {
+        this.running = Math.max(0, this.running - 1);
+        this.drain();
+    }
+    /** A szabad slot-okra besorol a várakozókból (FIFO), amíg van hely ÉS van várakozó. */
+    drain() {
+        while (this.running < this.maxConcurrency && this.waiters.length > 0) {
+            const next = this.waiters.shift();
+            if (next) {
+                this.running++;
+                next();
+            }
+        }
+    }
+    /** TESZT-only: a singleton eldobása (friss állapot a spec-ekhez). */
+    static resetForTest() {
+        FAM_OperationQueue_Service.instance = undefined;
+    }
+}
+exports.FAM_OperationQueue_Service = FAM_OperationQueue_Service;

package/build/src/_collections/fam-project-discovery.util.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ProjectDiscovery_Util = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const fam_famignore_util_1 = require("../_modules/ingest/_collections/fam-famignore.util");
+const fam_glob_match_util_1 = require("../_modules/ingest/_collections/fam-glob-match.util");
+/**
+ * `FAM_ProjectDiscovery_Util` (FEAT-008: a szerver-oldali scan-orchestráció magja, áthelyezve `_cli`→`_collections`)
+ * — projekt-gyökerek **auto-felderítése** egy mappa alatt + a config JSON-lista parse-je. PURE (fs-olvasás, nincs
+ * hálózat). A scope-nevet a `package.json` `name`-jéből deriválja, fallback a dir-név.
+ *
+ * **Felderítés-szabály:** egy könyvtár PROJEKT-GYÖKÉR, ha van `package.json` VAGY `.git`. Ott MEGÁLLUNK — EGY SCOPE
+ * PER REPO (user-decision 2026-06-24): a monorepo (`server`/`client`/`cli`/`e2e`) MIND egy közös repo-scope-ba kerül,
+ * NEM bontjuk al-csomag-scope-okra. A scope NEVE: monorepónál (van saját-markerű al-csomag) a REPO-DIR neve (a root
+ * `package.json` neve félrevezető lehet — pl. `@futdevpro/ccap` a `ccap-revisioned` monorepóra); egy-csomagos LEAF
+ * projektnél a `package.json` `name` bare alakja (a természetes identitás). A `node_modules` + rejtett mappák +
+ * `SKIP_DIRS` + `.fdpfamignore` kihagyva.
+ */
+class FAM_ProjectDiscovery_Util {
+    /** A projekt-gyökér markerek (bármelyik megléte → projekt). */
+    static MARKERS = ['package.json', '.git'];
+    /**
+     * A felderítésből MINDIG KIHAGYOTT könyvtárnevek (user-direktíva 2026-06-24, KRITIKUS — „SEMMIT nem akarunk
+     * szkennelni, ami a Stale-ben van!!!"). A `.fdpfamignore`-tól FÜGGETLEN, GARANTÁLT hard-skip: a `STALE-projects/`
+     * (archív/elavult projektek, pl. `fury` — 18757 fájl, „mind új" → halálra terheli az embedding-providert) +
+     * a `TEMPLATE-projects/` (`{{PROJECT_NAME}}` sablon-junk) + a `logs/` SOHA nem felderítendők. A `.`-mappák +
+     * `node_modules` külön (a startsWith('.') feltétel). Case-SENSITIVE (a workspace mappanevek pontos alakja).
+     */
+    static SKIP_DIRS = new Set([
+        'node_modules', 'STALE-projects', 'TEMPLATE-projects', 'logs',
+    ]);
+    /** Projekt-gyökér-e a könyvtár (van `package.json` vagy `.git`). */
+    static isProjectRoot(dir) {
+        return FAM_ProjectDiscovery_Util.MARKERS.some((marker) => (0, fs_1.existsSync)((0, path_1.join)(dir, marker)));
+    }
+    /** A scope leaf-név: a `package.json` `name` bare alakja (`@scope/x` → `x`), vagy a dir-név. */
+    static projectName(dir) {
+        try {
+            const pkgPath = (0, path_1.join)(dir, 'package.json');
+            if ((0, fs_1.existsSync)(pkgPath)) {
+                const name = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf-8')).name;
+                if (typeof name === 'string' && name.trim()) {
+                    return name.trim().replace(/^@[^/]+\//, '');
+                }
+            }
+        }
+        catch {
+            // fallback a dir-névre
+        }
+        return (0, path_1.basename)(dir);
+    }
+    /**
+     * Projekt-gyökerek felderítése `root` alatt `maxDepth`-ig. Ha a `root` maga projekt → csak az. Egyébként
+     * rekurzívan a nem-rejtett alkönyvtárakban (egy projekt-gyökérnél MEGÁLL). Determinisztikus (név szerint rendezett).
+     */
+    static discover(root, maxDepth, defaults) {
+        const result = [];
+        // A `.fdpfamignore` a FELDERÍTÉSRE is érvényes (user-FR 2026-06-22 — KRITIKUS bugfix): a famignore-olt mappákba
+        // (pl. a `Stale`-archív) NEM megyünk be, így a bennük lévő projekteket (pl. `fury`) NEM is fedezzük fel. A globok
+        // ROOT-relatívak (a `loadFromDir` baseDir-prefixe); a root + a nested famignore akkumulálódik a leszálláskor.
+        const relRoot = (dir) => (0, path_1.relative)(root, dir).replace(/\\/g, '/');
+        // A `dir` szűrt (nem-rejtett, nem-SKIP_DIRS, nem-famignore-olt) közvetlen al-KÖNYVTÁRAI (nevek). A
+        // monorepo-al-csomag-kereséshez ÉS a nem-projekt-leszálláshoz közös.
+        const filteredChildDirs = (dir, allGlobs) => {
+            let entries;
+            try {
+                entries = (0, fs_1.readdirSync)(dir).sort();
+            }
+            catch {
+                return [];
+            }
+            const dirs = [];
+            for (const name of entries) {
+                if (name.startsWith('.') || FAM_ProjectDiscovery_Util.SKIP_DIRS.has(name)) {
+                    continue;
+                }
+                const child = (0, path_1.join)(dir, name);
+                try {
+                    if (!(0, fs_1.statSync)(child).isDirectory()) {
+                        continue;
+                    }
+                }
+                catch {
+                    continue; // olvashatatlan bejegyzés → kihagyjuk
+                }
+                // FAMIGNORE-szűrés: a root-relatív útvonal VAGY a puszta mappanév egy ignore-globra illeszkedik → kihagyjuk.
+                const childRel = relRoot(child);
+                if (fam_glob_match_util_1.FAM_GlobMatch_Util.matchesAny(childRel, allGlobs) || fam_glob_match_util_1.FAM_GlobMatch_Util.matchesAny(name, allGlobs)) {
+                    continue;
+                }
+                dirs.push(name);
+            }
+            return dirs;
+        };
+        const visit = (dir, depth, ignoreGlobs) => {
+            if (depth > maxDepth) {
+                return;
+            }
+            // E könyvtár saját `.fdpfamignore`-ja (a root-relatív base-szel) → akkumulálva a leszármazottakra (a
+            // projekt-gyökérre IS, hogy a monorepo-leszálláskor + az al-csomag-keresésnél is érvényesüljön).
+            const localGlobs = fam_famignore_util_1.FAM_FamIgnore_Util.loadFromDir(dir, depth === 0 ? '' : relRoot(dir));
+            const allGlobs = localGlobs.length ? [...ignoreGlobs, ...localGlobs] : ignoreGlobs;
+            const childDirs = filteredChildDirs(dir, allGlobs);
+            if (FAM_ProjectDiscovery_Util.isProjectRoot(dir)) {
+                // ONE SCOPE PER REPO (user-decision 2026-06-24): a projekt-gyökeret EGY scope-ként vesszük fel, és NEM
+                // megyünk beljebb — a monorepo (server/client/cli/e2e) MIND egy közös repo-scope-ba kerül (nincs
+                // al-csomag-split, nincs lumpolás-aggály: szándékosan EGY repo = EGY scope). A scope NEVE: ha a gyökér
+                // alatt VAN saját-markerű al-csomag (FDP-monorepo), akkor a REPO-DIR neve — mert a root `package.json`
+                // neve félrevezető lehet (pl. `@futdevpro/ccap` a `ccap-revisioned` monorepóra → bare `ccap` → a téves
+                // `ccap-client` scope-ra oldódott). Egy-csomagos LEAF projektnél a `package.json` `name` (a természetes
+                // identitás → az NPM-package-ek scope-jai NEM neveződnek át). A monorepo-detekció depth-független
+                // (egy szinttel lejjebb nézünk; nem descend-elünk, ezért a maxDepth itt nem korlát).
+                const hasSubPackage = childDirs.some((name) => FAM_ProjectDiscovery_Util.isProjectRoot((0, path_1.join)(dir, name)));
+                result.push({
+                    path: dir,
+                    project: hasSubPackage ? (0, path_1.basename)(dir) : FAM_ProjectDiscovery_Util.projectName(dir),
+                    org: defaults?.org, table: defaults?.table,
+                });
+                return; // one scope per repo: nem megyünk beljebb
+            }
+            for (const name of childDirs) {
+                visit((0, path_1.join)(dir, name), depth + 1, allGlobs);
+            }
+        };
+        visit(root, 0, []);
+        return result;
+    }
+    /** A config JSON-lista → projekt-spec-ek (validálva: `path` + `project` kötelező soronként). */
+    static parseConfig(content) {
+        const parsed = JSON.parse(content);
+        if (!Array.isArray(parsed)) {
+            throw new Error('A scan-projects config egy JSON-tömb legyen: [{ "path": "...", "project": "..." }, ...]');
+        }
+        return parsed.map((raw, index) => {
+            const entry = (raw && typeof raw === 'object') ? raw : {};
+            if (typeof entry.path !== 'string' || typeof entry.project !== 'string') {
+                throw new Error(`A config[${index}] hiányos: a 'path' és a 'project' (string) kötelező.`);
+            }
+            return {
+                path: entry.path, project: entry.project,
+                org: typeof entry.org === 'string' ? entry.org : undefined,
+                table: typeof entry.table === 'string' ? entry.table : undefined,
+            };
+        });
+    }
+}
+exports.FAM_ProjectDiscovery_Util = FAM_ProjectDiscovery_Util;

package/build/src/_collections/fam-request-origin.util.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RequestOrigin_Util = void 0;
+/**
+ * `FAM_RequestOrigin_Util` (user-FR 2026-06-25) — egy FAM-esemény INDÍTÓJÁNAK aláírását (`FAM_AgentOrigin`) oldja fel a
+ * HTTP-kérésből: az `X-FAM-Session` / `X-FAM-Agent` / `X-FAM-Workspace` / `X-FAM-Label` headerekből VAGY a body `origin`
+ * mezőjéből (a body PER-MEZŐ felülír — explicit > header). Így a hívó (hook / `fam` CLI / agent) ALÁÍRJA az általa
+ * indított eseményt → több, EGYIDEJŰ workspace-session is megkülönböztethető. Aláírás teljes hiányában `agent:'unknown'`.
+ *
+ * A szerver NEM tudja kitalálni az identitást (a lokál portot minden session azonos forrásból éri el) — ezért a
+ * SZERZŐDÉS: a hívó adja meg. A FDP-agentek konvenciója: a CC `session_id`-t küldik az `X-FAM-Session` headerben.
+ */
+class FAM_RequestOrigin_Util {
+    /** A támogatott aláírás-headerek (kisbetűs — az Express így adja a `req.headers`-t). */
+    static HEADERS = [
+        { key: 'sessionId', header: 'x-fam-session' },
+        { key: 'agent', header: 'x-fam-agent' },
+        { key: 'workspace', header: 'x-fam-workspace' },
+        { key: 'label', header: 'x-fam-label' },
+    ];
+    /** A kérés (header + opcionális body-`origin`) → feloldott `FAM_AgentOrigin` (body felülír; üresnél `agent:'unknown'`). */
+    static fromRequest(req, bodyOrigin) {
+        const merged = {};
+        for (const entry of FAM_RequestOrigin_Util.HEADERS) {
+            const fromBody = bodyOrigin ? bodyOrigin[entry.key] : undefined;
+            const value = (fromBody && fromBody.trim()) ? fromBody.trim() : FAM_RequestOrigin_Util.header(req, entry.header);
+            if (value) {
+                merged[entry.key] = value;
+            }
+        }
+        const hasAny = Object.values(merged).some((value) => !!value);
+        return hasAny ? merged : { agent: 'unknown' };
+    }
+    /** Egy header string-értéke (trimmelve), vagy `undefined`. Tömb-header (ritka) első eleme. */
+    static header(req, name) {
+        const raw = req.headers[name];
+        const value = Array.isArray(raw) ? raw[0] : raw;
+        return value && value.trim() ? value.trim() : undefined;
+    }
+}
+exports.FAM_RequestOrigin_Util = FAM_RequestOrigin_Util;

package/build/src/_collections/fam-retry.util.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Retry_Util = void 0;
+/**
+ * `FAM_Retry_Util` — általános, ÚJRAHASZNÁLHATÓ retry-exponenciális-backoff helper a TRANZIENS hibákra
+ * (stresszteszt-lelet 2026-06-22: konkurrens terhelés alatt a remote embedding-provider ritkán megakadt → a
+ * teljes read elbukott egyetlen tranziens hibán). Pure-vezérelt (a `fn` async művelet + opciók), így a backoff
+ * `baseBackoffMs:0`-val determinisztikusan + gyorsan unit-tesztelhető.
+ *
+ * Az `isRetryable` predikátum dönti el, mi tranziens: a determinisztikus hibák (pl. validáció, dimenzió-mismatch)
+ * NEM retry-zhetők (azonnal dobnak), csak a hálózati/provider-átmenetiek. Az `onRetry` callback observability-re
+ * (warn-log) — a util maga NEM logol (függőség-mentes).
+ */
+class FAM_Retry_Util {
+    /**
+     * A `fn` futtatása `maxAttempts`-szor, exponenciális backoff-fal (`baseBackoffMs × 2^(n-1)`, `maxBackoffMs`-re
+     * kapozva) a próbálkozások KÖZÖTT. Siker → az eredmény. Ha az `isRetryable` `false`-t ad egy hibára → AZONNAL
+     * dobja (nincs további próba). A próbálkozások kimerülése → az UTOLSÓ hibát dobja (no-silent-failure).
+     */
+    static async withRetry(fn, options) {
+        const maxAttempts = Math.max(1, Math.floor(options.maxAttempts));
+        const base = options.baseBackoffMs ?? 250;
+        const cap = options.maxBackoffMs ?? 1000;
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                if (options.isRetryable && !options.isRetryable(error)) {
+                    throw error;
+                }
+                if (attempt < maxAttempts) {
+                    const backoffMs = Math.min(cap, base * 2 ** (attempt - 1));
+                    if (options.onRetry) {
+                        options.onRetry(attempt, backoffMs, error);
+                    }
+                    if (backoffMs > 0) {
+                        await new Promise((resolveSleep) => setTimeout(resolveSleep, backoffMs));
+                    }
+                }
+            }
+        }
+        throw lastError;
+    }
+}
+exports.FAM_Retry_Util = FAM_Retry_Util;

package/build/src/_collections/fam-scan-progress-sink.service.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScanProgress_Sink = void 0;
+/**
+ * `FAM_ScanProgress_Sink` (FEAT-008 sub-progress, user-FR 2026-06-22) — a LEGUTÓBBI projekten-belüli haladás
+ * process-szintű holder-e. Mivel az operation-queue szerializál (egyszerre EGY projekt ingestál), egyetlen „latest"
+ * elég. Az ingest a throttle-olt progress-emitkor frissíti; a scan-job a `getStatus`-ban beolvassa → a thin-CLI
+ * poll is látja a within-project haladást (nem csak a per-projekt befejezést). Statikus, állapot-minimal.
+ */
+class FAM_ScanProgress_Sink {
+    /** A legutóbbi haladás-pillanatkép (vagy undefined, ha még nem volt / törölve). */
+    static latest;
+    /** A legutóbbi haladás beállítása (az ingest hívja a progress-emitnél). */
+    static set(progress) {
+        FAM_ScanProgress_Sink.latest = progress;
+    }
+    /** A legutóbbi haladás (a scan-job status-hoz). */
+    static get() {
+        return FAM_ScanProgress_Sink.latest;
+    }
+    /** A holder ürítése (teszt / projekt-váltás). */
+    static clear() {
+        FAM_ScanProgress_Sink.latest = undefined;
+    }
+}
+exports.FAM_ScanProgress_Sink = FAM_ScanProgress_Sink;

package/build/src/_enums/fam-rule-scope.type-enum.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RuleScope = void 0;
+/**
+ * `FAM_RuleScope` (Rules-Management System, MP-1) — egy szabály ALKALMAZHATÓSÁGI osztálya: HOL érvényes + injektálódik.
+ * (Megkülönböztetve a `scopePath`-tól, ami a scope-ENTITÁS-lánc — itt a rule always-apply TIER-jéről van szó.)
+ *
+ * - `global`          — univerzális; MINDEN rendszerre (FDP + nem-FDP), root ÉS in-project. Mindig injektált.
+ * - `fdpGlobal`       — FDP-ökoszisztéma-specifikus (FDP CLI, Keystore, bedrock, Dynamo/NTS, FAM, @futdevpro). Csak FDP-repóban.
+ * - `workspaceRoot`   — CSAK a multi-projekt workspace root-szinten (orchestráció / cross-project / devops).
+ * - `projectInternal` — minden projektben, amikor az agent a projekt-workspace-en belül dolgozik.
+ * - `projectType`     — projekt-TÍPUS szerint (a `ruleScopeTopic` adja a típust, pl. `ngx`/`nts`/`server`/`client`).
+ * - `trigger`         — on-demand, kontextus/téma szerint (a `ruleScopeTopic` a téma; a rule-fetch-reflex hozza elő).
+ *
+ * Konvenció: `keyNameIsCamelCase = 'value-is-kebab-case'`.
+ */
+var FAM_RuleScope;
+(function (FAM_RuleScope) {
+    FAM_RuleScope["global"] = "global";
+    FAM_RuleScope["fdpGlobal"] = "fdp-global";
+    FAM_RuleScope["workspaceRoot"] = "workspace-root";
+    FAM_RuleScope["projectInternal"] = "project-internal";
+    FAM_RuleScope["projectType"] = "project-type";
+    FAM_RuleScope["trigger"] = "trigger";
+})(FAM_RuleScope || (exports.FAM_RuleScope = FAM_RuleScope = {}));

package/build/src/_models/data-models/fam-entry.data-model.js

@@ -22,6 +22,14 @@ class FAM_Entry extends fsm_dynamo_1.DyFM_Metadata {
     kind;
     /** Többes kategorizálás (dsgn-001 §3); per-tár ajánlott vokabulár, de szabadon bővül. */
     tags = [];
+    /**
+     * **GLOBÁLIS HARD-RULE** jelölő (user-FR 2026-06-22 — a FAM egyik fő feature-je): ha `true`, ez a (jellemzően
+     * `rules`-táras) bejegyzés MINDEN scope-szűrt lekérdezésbe BEKERÜL, scope-tól FÜGGETLENÜL — a workspace-szintű
+     * hard-rules (pl. E2E-hard-rule, always-master, naming/import-konvenciók) így öröklődnek MINDEN al-scope rule-
+     * lekérdezésébe. A retrieval candidate-prefilter `$or`-ral húzza be (`scopePath.scopeId $in subtree` VAGY
+     * `globalRule:true`). Default `false` (a legtöbb rule scope-specifikus); a hard-rules EXPLICIT jelölést kapnak.
+     */
+    globalRule;
     // --- tartalom + embedding ---
     /** A vektorizált, ember-olvasható szöveg (kanonikus mező — dsgn-001 §2). */
     content;
@@ -49,6 +57,27 @@ class FAM_Entry extends fsm_dynamo_1.DyFM_Metadata {
     weight = 1;
     /** Opcionális kvalitatív hangsúly (0..1). */
     importance;
+    // --- Memory Activation Model (dsgn-013, CSAK a `memory` táron értelmezett) ---
+    /**
+     * Az utolsó FELIDÉZÉS (recall) epoch-ms-e — a lazy recency-decay bemenete (dsgn-013 §2). A `read` által
+     * visszaadott top-K memory-hitre frissül (F2). Default a létrehozás ideje (cold-start kegyelmi idő: egy
+     * frissen-szkennelt RÉGI memória ne tűnjön azonnal dormant-nak). NEM-memory táron értelmetlen (decayFactor=1).
+     */
+    lastRecalledAt;
+    /** Hányszor lett FELIDÉZVE (dsgn-013 §2) — a telítődő frequency-megerősítés bemenete (`1 + log2(1+recallCount)`). */
+    recallCount = 0;
+    /**
+     * ALVÓ-e (dsgn-013 §5): a degradáció-küszöb alá esett, régóta nem-felidézett memória — NEM hidratálódik a hot
+     * LVS-poolba (RAM-/boot-spórolás), de Mongo-oldali COLD kereséssel elérhető (+ megtalálásakor reaktiválódik).
+     * SOHA nem jelent törlést (a tartalom megmarad). Indexelt a `memory` data-paramsban (a hidratálás-szűrőhöz).
+     */
+    dormant;
+    /**
+     * LEVÁLTOTT-e (superseded, dsgn-013 §6, MAM F4): egy additív (`memory`) fájl RÉGI tartalma, amit egy újabb
+     * szken átírt/kivett (pl. kompaktálás). NEM törlés — megőrizve + cold-kereshető, de a ranking penalizálja
+     * (`memory.supersededPenalty`), így a friss verzió fölébe kerül. A content-addressed additív delta jelöli.
+     */
+    superseded;
     // --- forrás / pozíció (scan/import esetén) ---
     /** Provenance (dsgn-001 §6). */
     source;

package/build/src/_models/data-models/fam-memory.data-model.js

@@ -51,5 +51,10 @@ exports.famMemory_dataParams = new fsm_dynamo_1.DyFM_DataModel_Params({
         runId: { type: 'string', index: true },
         instanceId: { type: 'string', index: true },
         summarizedEntryIds: { type: 'string[]', default: [] },
+        // Memory Activation Model (dsgn-013) — CSAK a memory táron perzisztált. `dormant` indexelt a hidratálás-szűrőhöz.
+        lastRecalledAt: { type: 'number' },
+        recallCount: { type: 'number', default: 0 },
+        dormant: { type: 'boolean', index: true },
+        superseded: { type: 'boolean', index: true },
     },
 });

package/build/src/_models/data-models/fam-rules.data-model.js

@@ -10,6 +10,14 @@ const fam_entry_data_model_1 = require("./fam-entry.data-model");
  * A `FAM_Entry` bázisra épül; per-tár mezők: `category` (== `kind`), `isActive` (inaktív szabály
  * NEM retrieve-elődik), `applicableScopes` (üres = globális), `dimensions`.
  * `kind` default `'rule'`, `isActive` default `true` (dsgn-001 §4).
+ *
+ * **Rules-Management System (MP-1)** — injektálás-aware mezők:
+ * - `ruleScope`/`ruleScopeTopic` — always-apply TIER (lásd `FAM_RuleScope`); a `<topic>` suffix a
+ *   `projectType`/`trigger` esetén külön (`ruleScopeTopic`, pl. `'ngx'` / `'docker'`).
+ * - `userApproved` — a user EGYESÉVEL jóváhagyta-e (a curated-core hard-rule gate-je).
+ * - `ruleId` — stabil, ember-olvasható azonosító (pl. `'G-trace'`, `'PI3'`) — propagáció/dedup kulcs.
+ * - `derivedFrom` — ha propagált/származtatott: a kanonikus forrás-`ruleId` (dedup → 1 canonical + N provenance).
+ * - `importance` (a bázison) a rules-rendszerben **0–100** skálán rangsorol injektáláskor (MP-2).
  */
 class FAM_Rules_DataModel extends fam_entry_data_model_1.FAM_Entry {
     /** Kategória (== `kind`; pl. `'coding'` / `'project'` / `'naming'`). */
@@ -20,6 +28,16 @@ class FAM_Rules_DataModel extends fam_entry_data_model_1.FAM_Entry {
     applicableScopes = [];
     /** Dimenziók (`server`|`client`|`fullstack`|`devops`|`testing`). */
     dimensions = [];
+    /** Always-apply TIER osztály (MP-1; `FAM_RuleScope`). Üres = nincs besorolva (legacy / nem-tier). */
+    ruleScope;
+    /** A `projectType`/`trigger` TIER témája (pl. `'ngx'` / `'docker'`); más tier-eknél üres. */
+    ruleScopeTopic;
+    /** A user EGYESÉVEL approve-olta-e (curated-core hard-rule gate). */
+    userApproved = false;
+    /** Stabil, ember-olvasható azonosító (pl. `'G-trace'`, `'PI3'`) — propagáció/dedup kulcs. */
+    ruleId;
+    /** Propagált/származtatott szabálynál a kanonikus forrás-`ruleId` (dedup-provenance). */
+    derivedFrom;
     constructor(set) {
         super(set);
         if (set) {
@@ -45,7 +63,13 @@ exports.famRules_dataParams = new fsm_dynamo_1.DyFM_DataModel_Params({
         },
         category: { type: 'string', index: true },
         isActive: { type: 'boolean', index: true, default: true },
+        globalRule: { type: 'boolean', index: true },
         applicableScopes: { type: 'array', default: [] },
         dimensions: { type: 'string[]', index: true, default: [] },
+        ruleScope: { type: 'string', index: true },
+        ruleScopeTopic: { type: 'string', index: true },
+        userApproved: { type: 'boolean', index: true, default: false },
+        ruleId: { type: 'string', index: true },
+        derivedFrom: { type: 'string', index: true },
     },
 });

package/build/src/_models/data-models/fam-scan-job.data-model.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.famScanJob_dataParams = exports.FAM_ScanJob_DataModel = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+/**
+ * `FAM_ScanJob_DataModel` (FEAT-008 Phase 4, user-FR 2026-06-22) — egy szerver-oldali scan-job DURABLE pillanatképe
+ * a `fam_scan_jobs` collection-ben. Cél: a job (per-projekt állapottal) TÚLÉLJE a server-restart/crash/close-t, és a
+ * szerver **AUTO-RESUME-olja a megszakítási ponttól** (a már `ok` projekteket átugorva). A `projects[]` a per-projekt
+ * checkpoint (státusz + eredmény); a `specs[]` az újrafuttatáshoz kell (path/project/org/table). `extends DyFM_Metadata`.
+ *
+ * A `jobId` a UUID (mező, indexelt) — NEM a `_id` (a Dynamo a `_id`-t ObjectId-ra cast-olja, a client-UUID nem fér).
+ */
+class FAM_ScanJob_DataModel extends fsm_dynamo_1.DyFM_Metadata {
+    /** A job UUID-ja (a getStatus/resume ezen keres). */
+    jobId;
+    /** A globális státusz. */
+    status;
+    /** A projektek száma. */
+    total;
+    /** A jelenleg feldolgozott projekt indexe. */
+    currentIndex;
+    /** A sikeres projektek száma. */
+    okCount;
+    /** A projektek közti cooldown (ms). */
+    cooldownMs;
+    /** A feltételes cooldown küszöbe. */
+    cooldownMinChunks;
+    /** Indítás epoch-ms. */
+    startedAt;
+    /** Befejezés epoch-ms (ha kész). */
+    finishedAt;
+    /** Per-projekt checkpoint (státusz + eredmény) — a resume ebből tudja, mi van már kész. */
+    projects = [];
+    /** A scan-specifikációk (a resume újrafuttatásához: path/project/org/table). */
+    specs = [];
+    /** A hívó (CLI) start/source location-je — a resume-kori path-feloldáshoz. */
+    sourceLocation;
+    /** Hányszor lett már auto-resume-olva (FEAT-008 Phase 5) — a resume-loop elleni cap (`scan.maxResumeCount`) bemenete. */
+    resumeCount;
+    /** Terminál ok-szöveg (pl. „resume-cap túllépve") — `failed`/`cancelled` job-on, a diagnózishoz. */
+    failureReason;
+    constructor(set) {
+        super(set);
+        if (set) {
+            fsm_dynamo_1.DyFM_Object.cleanAssign(this, set);
+        }
+    }
+}
+exports.FAM_ScanJob_DataModel = FAM_ScanJob_DataModel;
+/**
+ * MongoDB data-params a `fam_scan_jobs` collection-höz (FEAT-008 Phase 4). Nincs vektor-mező (a job nem retrieve-elhető
+ * tartalom). A `jobId` + `status` indexelt (a getStatus + a resume-lekérdezés gyors útja).
+ */
+exports.famScanJob_dataParams = new fsm_dynamo_1.DyFM_DataModel_Params({
+    dataName: 'fam_scan_jobs',
+    addArchive: true,
+    properties: {
+        jobId: { type: 'string', index: true },
+        status: { type: 'string', index: true },
+        total: { type: 'number' },
+        currentIndex: { type: 'number' },
+        okCount: { type: 'number' },
+        cooldownMs: { type: 'number' },
+        cooldownMinChunks: { type: 'number' },
+        startedAt: { type: 'number' },
+        finishedAt: { type: 'number' },
+        projects: { type: 'array', default: [] },
+        specs: { type: 'array', default: [] },
+        sourceLocation: { type: 'string' },
+        resumeCount: { type: 'number' },
+        failureReason: { type: 'string' },
+    },
+});