npm - @futdevpro/fdp-agent-memory - Versions diffs - 0.1.0 - Mend

@futdevpro/fdp-agent-memory 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (117) hide show

package/build/src/_routes/server/client-app/client-app.control-service.js ADDED Viewed

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientApp_ControlService = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const express_1 = tslib_1.__importDefault(require("express"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+/**
+ * A beépített Angular admin-UI (`client-dist`) kiszolgálása. A klienst a build-lépés (`build-ui-for-publish`,
+ * dsgn-012 §9) a `server/client-dist`-be másolja, és a publikált package `files`-ében ship-elődik — így
+ * EGY `fam start` (vagy a lokál Docker-image) a teljes felületet adja localhoston, külön kliens-process
+ * NÉLKÜL (dsgn-011 / dsgn-012; a `ccap-revisioned` `SC_ClientStatic` mintára).
+ *
+ * Mount: a routing-modul route `/app`, a DyNTS `baseUrl='/api'` elé fűzi → a UI a **`/api/app`** alatt él
+ * (a build base-href ezért `/api/app/`). A req.url-ből MINDKÉT lehetséges prefixet (`/api/app`, `/app`)
+ * levágjuk, mert a framework levághatja az `/api`-t.
+ */
+const CLIENT_DIST_CANDIDATES = [
+    // build:   server/build/src/_routes/server/client-app/ → 5 szint fel a server/-ig
+    path.resolve(__dirname, '..', '..', '..', '..', '..', 'client-dist'),
+    // ts-node: server/src/_routes/server/client-app/ → 4 szint fel a server/-ig
+    path.resolve(__dirname, '..', '..', '..', '..', 'client-dist'),
+    // futtatási könyvtárból (pl. Docker WORKDIR /app)
+    path.resolve(process.cwd(), 'client-dist'),
+];
+const CLIENT_DIST_PATH = CLIENT_DIST_CANDIDATES.find((candidate) => fs.existsSync(candidate)) ?? CLIENT_DIST_CANDIDATES[0];
+/** A UI mount-prefixei (a static-fájl feloldáshoz a req.url-ből levágandók). */
+const API_APP_MOUNT_PATH = '/api/app';
+const APP_MOUNT_PATH = '/app';
+/** Base href az index.html-be — az asset-ek így `/api/app/` alól töltődnek. */
+const BASE_HREF_FOR_APP = '/api/app/';
+/** Fallback HTML, ha nincs `client-dist` (pl. dev-ben még nem épült) — a gyökér ne adjon 404-et. */
+const FALLBACK_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>FDP Agent Memory — server running</title>
+</head>
+<body>
+  <h1>FDP Agent Memory server is running</h1>
+  <p>The admin UI is not built yet. Options:</p>
+  <ul>
+    <li>From the repo: run <code>pnpm run build-ui-for-publish</code> (server), then reload.</li>
+    <li>Dev: start the Angular dev server in <code>client/</code> (<code>pnpm start</code>) at <code>http://localhost:4205</code>.</li>
+  </ul>
+</body>
+</html>`;
+/**
+ * `ClientApp_ControlService` — a beépített kliens-UI statikus kiszolgálásának logikája (a thin controller
+ * ide delegál). `init()` a mount-kor ellenőrzi a `client-dist` meglétét; `handleRequest` static-fájlt vagy
+ * SPA-fallback (base-href-injektált index.html) szolgál ki, hiányzó dist esetén fallback HTML-t.
+ */
+class ClientApp_ControlService extends nts_dynamo_1.DyNTS_SingletonService {
+    static getInstance() {
+        return ClientApp_ControlService.getSingletonInstance();
+    }
+    staticMiddleware = null;
+    indexPath = '';
+    isClientDistAvailable = false;
+    /** Mount-kori inicializálás (a controller `setupEndpoints`-ból): a `client-dist` meglét + static-middleware. */
+    init() {
+        this.isClientDistAvailable = fs.existsSync(CLIENT_DIST_PATH);
+        if (!this.isClientDistAvailable) {
+            fsm_dynamo_1.DyFM_Log.info('FDP Agent Memory UI: client-dist hiányzik — fallback HTML szolgál ki a gyökéren.');
+            return { isClientDistAvailable: false, clientDistPath: CLIENT_DIST_PATH };
+        }
+        // index:false — az index.html-t NE az express.static adja ki közvetlenül; a SPA-fallbacken megy át,
+        // ami a helyes base-href-et (`/api/app/`) injektálja, függetlenül a build base-href-jétől.
+        this.staticMiddleware = express_1.default.static(CLIENT_DIST_PATH, {
+            index: false,
+            setHeaders: (res, filePath) => {
+                if (filePath.endsWith('.map')) {
+                    res.setHeader('Content-Type', 'application/json');
+                }
+            },
+        });
+        this.indexPath = path.resolve(CLIENT_DIST_PATH, 'index.html');
+        fsm_dynamo_1.DyFM_Log.info(`FDP Agent Memory UI kiszolgálása: ${CLIENT_DIST_PATH} (statikus + SPA-fallback, /api/app).`);
+        return { isClientDistAvailable: true, clientDistPath: CLIENT_DIST_PATH };
+    }
+    /** A `GET *` handler: dist-állapot szerint static+SPA-fallback, vagy fallback HTML. */
+    async handleRequest(req, res, issuer) {
+        if (this.isClientDistAvailable) {
+            await this.handleServeClient(req, res, issuer);
+            return;
+        }
+        await this.handleFallback(req, res, issuer);
+    }
+    /** Fallback HTML (nincs client-dist). */
+    async handleFallback(_req, res, _issuer) {
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.status(200).send(FALLBACK_HTML);
+    }
+    /** Static-fájl vagy SPA-fallback (base-href-injektált index.html). */
+    async handleServeClient(req, res, _issuer) {
+        const staticMiddleware = this.staticMiddleware;
+        const indexPath = this.indexPath;
+        const serveIndex = () => {
+            if (fs.existsSync(indexPath)) {
+                const raw = fs.readFileSync(indexPath, 'utf-8');
+                const withBase = raw.replace(/<base\s+href="[^"]*"\s*\/?>/i, `<base href="${BASE_HREF_FOR_APP}">`);
+                res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                res.status(200).send(withBase);
+            }
+            else {
+                res.status(404).send('Not found');
+            }
+        };
+        if (!staticMiddleware) {
+            serveIndex();
+            return;
+        }
+        // A static-middleware a client-dist gyökeréhez viszonyít — a mount-prefixeket le kell vágni.
+        const originalUrl = req.url;
+        let relativeUrl = originalUrl.replace(this.prefixRegExp(API_APP_MOUNT_PATH), '/');
+        relativeUrl = relativeUrl.replace(this.prefixRegExp(APP_MOUNT_PATH), '/');
+        req.url = relativeUrl || '/';
+        staticMiddleware(req, res, () => {
+            req.url = originalUrl;
+            serveIndex();
+        });
+    }
+    /** Egy mount-prefix-levágó regexp (a regexp-meta karakterek escapelve). */
+    prefixRegExp(mountPath) {
+        const escaped = mountPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`^${escaped}/?`);
+    }
+}
+exports.ClientApp_ControlService = ClientApp_ControlService;

package/build/src/_routes/server/client-app/client-app.controller.js ADDED Viewed

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientApp_Controller = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const client_app_control_service_1 = require("./client-app.control-service");
+/**
+ * `ClientApp_Controller` — a beépített Angular admin-UI kiszolgálása (route `/app` → DyNTS `baseUrl='/api'`
+ * elé fűzve → **`/api/app`**). Egyetlen `GET *` catch-all: static-fájl, ha van; egyébként SPA-fallback
+ * (base-href-injektált index.html); ha nincs `client-dist`, fallback HTML (a gyökér ne 404-ezzen).
+ *
+ * Thin controller (csak delegálás a `ClientApp_ControlService`-re — nincs logika/validáció). Singleton.
+ */
+class ClientApp_Controller extends nts_dynamo_1.DyNTS_Controller {
+    static getInstance() {
+        return ClientApp_Controller.getSingletonInstance();
+    }
+    clientApp_CS = client_app_control_service_1.ClientApp_ControlService.getInstance();
+    setupEndpoints() {
+        this.clientApp_CS.init();
+        this.endpoints = [
+            new nts_dynamo_1.DyNTS_Endpoint_Params({
+                name: 'serveClientOrFallback',
+                type: fsm_dynamo_1.DyFM_HttpCallType.get,
+                endpoint: '*',
+                tasks: [
+                    async (req, res, issuer) => {
+                        await this.clientApp_CS.handleRequest(req, res, issuer);
+                    },
+                ],
+            }),
+        ];
+    }
+}
+exports.ClientApp_Controller = ClientApp_Controller;

package/build/src/_routes/server/config/config.control-service.js ADDED Viewed

@@ -0,0 +1,476 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Config_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const fam_config_level_type_enum_1 = require("../../../_enums/fam-config-level.type-enum");
+const config_catalog_const_1 = require("../../../_collections/config-catalog.const");
+const config_error_codes_const_1 = require("../../../_collections/config-error-codes.const");
+const config_presets_const_1 = require("../../../_collections/config-presets.const");
+const fam_config_data_model_1 = require("../../../_models/data-models/fam-config.data-model");
+const config_data_service_1 = require("./config.data-service");
+/**
+ * `FAM_Config_ControlService` — a DB-backed, scoped config feloldó-szolgáltatás (dsgn-007 §8).
+ *
+ * Singleton. Tartja a `CONFIG_CATALOG`-ot (§4), a preseteket (§5), a validációt (§7) és a cache-t (§3).
+ * `resolve(key, ctx)` a legspecifikusabb beállított értéket adja **scope > table > global > builtin**
+ * precedenciával; `resolveAll(ctx)` a teljes effektív config egy Mongo-körrel. **BFR-AM-004
+ * projekt-lokális workaround** — a `resolve`/`resolveAll`/`set` API-kontraktusa STABIL, hogy a
+ * jövőbeli `DyNTS_ScopedConfig_*` bedrock-csere non-breaking legyen.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** NEM tartunk élő `FAM_Config_DataService`
+ * mezőt (eager DB-resolve a base-ctor-ban) — minden DB-művelet előtt lazy `new FAM_Config_DataService`.
+ */
+class FAM_Config_ControlService {
+    static _instance;
+    /** Default issuer a config-műveletekhez (a hibák `issuer`-éhez, dsgn-008). */
+    issuer = 'FAM_Config_ControlService';
+    /** Rövid-TTL memória-cache (kulcs: kontextus-szelet; `set`/`applyPreset` invalidálja, dsgn-007 §3). */
+    cache = new Map();
+    /** A cache TTL ms-ben (~60s, a `reference.cacheTtlMs` builtin-jével összhangban). */
+    cacheTtlMs = 60000;
+    static getInstance() {
+        if (!FAM_Config_ControlService._instance) {
+            FAM_Config_ControlService._instance = new FAM_Config_ControlService();
+        }
+        return FAM_Config_ControlService._instance;
+    }
+    // =========================================================================
+    // RESOLVE (dsgn-007 §3) — precedencia: scope (leaf→root) > table > global > builtin
+    // =========================================================================
+    /**
+     * Egy kulcs feloldása a legspecifikusabb beállított értékre (dsgn-007 §3). A precedencia:
+     * (1) SCOPE szint a `scopePath` LEVELÉBŐL a gyökér felé (az első/legmélyebb találat nyer),
+     * (2) TABLE szint, (3) GLOBAL szint, (4) `CONFIG_CATALOG[key].default` builtin (mindig van).
+     *
+     * A `scopePath` canonical formában érkezik (a read/write-path a reference-resolveren átfuttatta).
+     */
+    async resolve(key, context) {
+        this.assertKnownKey(key);
+        const records = await this.loadEffectiveRecords(context);
+        return this.resolveFromRecords(key, records, context);
+    }
+    /**
+     * A teljes effektív config egy adott kontextusra (dsgn-007 §3 batch). EGY Mongo-kör (cache-elt),
+     * majd memóriában merge: minden katalógus-kulcsra a feloldott érték + forrás-szint. A hot-path
+     * (read/write) ezt használja, nem per-key kört.
+     */
+    async resolveAll(context) {
+        const records = await this.loadEffectiveRecords(context);
+        const result = {};
+        for (const key of this.allKeys()) {
+            result[key] = this.resolveFromRecords(key, records, context);
+        }
+        return result;
+    }
+    /**
+     * A feloldott effektív érték + forrás-szint (dsgn-007 §7.2). A `capabilities` `get_config_status`
+     * / CLI `config get` / UI ezt használja: átlátható, HONNAN jön egy érték.
+     */
+    async getConfigStatus(key, context) {
+        return this.resolve(key, context);
+    }
+    /**
+     * A `resolve` mag (memóriában, a betöltött rekord-halmazon). Külön metódus, hogy a `resolveAll`
+     * is ezt használja (egyetlen Mongo-kör után minden kulcsra).
+     */
+    resolveFromRecords(key, records, context) {
+        const table = context?.table;
+        const scopePath = context?.scopePath ?? [];
+        // 1. SCOPE szint — a scopePath leveléből a gyökér felé (leaf→root); az első találat nyer.
+        if (table && scopePath.length) {
+            for (let i = scopePath.length - 1; i >= 0; i--) {
+                const scopeId = scopePath[i].scopeId;
+                const hit = records.find((rec) => rec.level === fam_config_level_type_enum_1.FAM_ConfigLevel.scope && rec.tableScope === table && rec.scopeId === scopeId && rec.key === key);
+                if (hit) {
+                    return this.toResolved(hit, 'scope');
+                }
+            }
+        }
+        // 2. TABLE szint.
+        if (table) {
+            const hit = records.find((rec) => rec.level === fam_config_level_type_enum_1.FAM_ConfigLevel.table && rec.tableScope === table && rec.key === key);
+            if (hit) {
+                return this.toResolved(hit, 'table');
+            }
+        }
+        // 3. GLOBAL szint.
+        const globalHit = records.find((rec) => rec.level === fam_config_level_type_enum_1.FAM_ConfigLevel.global && rec.key === key);
+        if (globalHit) {
+            return this.toResolved(globalHit, 'global');
+        }
+        // 4. builtin default (mindig van — dsgn-007 §3 / §10.3).
+        return {
+            value: config_catalog_const_1.CONFIG_CATALOG[key].default,
+            resolvedFrom: 'builtin',
+        };
+    }
+    /** Egy DB-rekordot a feloldott-érték shape-re (a forrás-szinttel + audittal). */
+    toResolved(record, resolvedFrom) {
+        return {
+            value: record.value,
+            resolvedFrom: resolvedFrom,
+            scopeId: record.scopeId,
+            setBy: record.setBy,
+            setByDetail: record.setByDetail,
+        };
+    }
+    /**
+     * A kontextusra releváns aktív rekordok betöltése EGY Mongo-körrel (dsgn-007 §3), cache-elve.
+     * A filter a global + (ha van) table + a scopePath összes scopeId-jára szűkít — így a merge
+     * memóriában fut. `set`/`applyPreset` invalidál.
+     */
+    async loadEffectiveRecords(context) {
+        const cacheKey = this.cacheKey(context);
+        const cached = this.cache.get(cacheKey);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.records;
+        }
+        const orClauses = [{ level: fam_config_level_type_enum_1.FAM_ConfigLevel.global }];
+        if (context?.table) {
+            orClauses.push({ level: fam_config_level_type_enum_1.FAM_ConfigLevel.table, tableScope: context.table });
+            const scopeIds = (context.scopePath ?? []).map((ref) => ref.scopeId);
+            if (scopeIds.length) {
+                orClauses.push({ level: fam_config_level_type_enum_1.FAM_ConfigLevel.scope, tableScope: context.table, scopeId: { $in: scopeIds } });
+            }
+        }
+        const dataService = new config_data_service_1.FAM_Config_DataService({ issuer: this.issuer });
+        const records = await dataService.findActiveList({ $or: orClauses });
+        this.cache.set(cacheKey, { records: records, expiresAt: Date.now() + this.cacheTtlMs });
+        return records;
+    }
+    /** A cache-kulcs egy kontextus-szeletre (table + a scopePath scopeId-lánca). */
+    cacheKey(context) {
+        const table = context?.table ?? '-';
+        const scopeIds = (context?.scopePath ?? []).map((ref) => ref.scopeId).join('>') || '-';
+        return `${table}|${scopeIds}`;
+    }
+    /** A teljes cache invalidálása (`set`/`applyPreset` után — dsgn-007 §3). */
+    invalidateCache() {
+        this.cache.clear();
+    }
+    // =========================================================================
+    // SET (dsgn-007 §7) — validate → archive-old → write-new → invalidate cache
+    // =========================================================================
+    /**
+     * Egy config-érték beállítása egy adott szinten (dsgn-007 §7). A `set`:
+     * (1) validál a `CONFIG_CATALOG` ellen (típus / tartomány / szint / scope; `FAM-CONFIG-SET-00x`),
+     * (2) a ugyanazon `(level,tableScope,scopeId,key)` kulcson lévő AKTÍV régi rekordot soft-delete-eli
+     *     (archív → history), (3) az új aktív rekordot `$set`-tel írja (Mixed atomikus), (4) invalidál.
+     */
+    async set(key, value, options) {
+        await this.validate(key, value, options);
+        const filter = this.levelKeyFilter(key, options);
+        const dataService = new config_data_service_1.FAM_Config_DataService({ issuer: options.issuer ?? this.issuer });
+        // Régi aktív rekord (ha van) → soft-delete (archív; history-megőrzés, dsgn-007 §7.2).
+        const existing = await dataService.findActive(filter);
+        if (existing && existing._id) {
+            await dataService.deleteData(existing._id);
+        }
+        // Új aktív rekord — a `value` Mixed; a saveData $set-tel ír (Mongoose Mixed silent-drop ellen).
+        const record = new fam_config_data_model_1.FAM_Config_DataModel({
+            level: options.level,
+            tableScope: options.tableScope,
+            scopeId: options.scopeId,
+            key: key,
+            value: value,
+            setBy: options.setBy ?? 'system',
+            setByDetail: options.setByDetail,
+            note: options.note,
+        });
+        const writeService = new config_data_service_1.FAM_Config_DataService({ data: record, issuer: options.issuer ?? this.issuer });
+        const saved = await writeService.saveData(record);
+        this.invalidateCache();
+        return saved;
+    }
+    /** A `(level, tableScope, scopeId, key)` feloldási-kulcs filtere (a logikai unique-constraint). */
+    levelKeyFilter(key, options) {
+        const filter = { level: options.level, key: key };
+        if (options.level === fam_config_level_type_enum_1.FAM_ConfigLevel.table || options.level === fam_config_level_type_enum_1.FAM_ConfigLevel.scope) {
+            filter.tableScope = options.tableScope;
+        }
+        if (options.level === fam_config_level_type_enum_1.FAM_ConfigLevel.scope) {
+            filter.scopeId = options.scopeId;
+        }
+        return filter;
+    }
+    // =========================================================================
+    // VALIDATE (dsgn-007 §7.1) — FAM-CONFIG-SET-001..006
+    // =========================================================================
+    /**
+     * A `set`-kori validáció (dsgn-007 §7.1). Lehetetlen érték → deskriptív hiba (a "néma hiba tilos");
+     * a hibakódok a dsgn-007 §7 SSOT-ból (`FAM-CONFIG-SET-001..006`).
+     *
+     * A scope-létezés (`FAM-CONFIG-SET-006`) ellenőrzése MP-3 (`FAM_Scope`) függő: itt a `scopeId`
+     * jelenlétét kötelezővé tesszük scope-szinten; a tényleges scope-lét ellenőrzés MP-3 után
+     * aktiválható (a kontraktus stabil).
+     */
+    async validate(key, value, options) {
+        const entry = this.assertKnownKey(key);
+        // Szint-értelmezés (FAM-CONFIG-SET-005).
+        this.validateLevel(key, entry, options);
+        // Típus (FAM-CONFIG-SET-002).
+        this.validateType(key, entry, value);
+        // Tartomány / enum (FAM-CONFIG-SET-003).
+        this.validateRange(key, entry, value);
+        // Cross-field invariáns (FAM-CONFIG-SET-004) a feloldott kontextusban.
+        await this.validateCrossField(key, value, options);
+        // Scope-azonosítás (FAM-CONFIG-SET-006) — scope-szinten a scopeId kötelező.
+        if (options.level === fam_config_level_type_enum_1.FAM_ConfigLevel.scope && !options.scopeId) {
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setScopeNotFound, `Config '${key}' scope-szintű beállításához kötelező a scopeId (létező aktív FAM_Scope).`, options.issuer);
+        }
+    }
+    /** Ismeretlen kulcs → `FAM-CONFIG-SET-001` (hasonló-kulcs javaslattal). */
+    assertKnownKey(key) {
+        const entry = config_catalog_const_1.CONFIG_CATALOG[key];
+        if (!entry) {
+            const suggestions = this.similarKeys(key);
+            const hint = suggestions.length ? ` Hasonló kulcsok: ${suggestions.join(', ')}.` : '';
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setUnknownKey, `Ismeretlen config-kulcs: '${key}'. A kulcs nincs a CONFIG_CATALOG-ban.${hint}`);
+        }
+        return entry;
+    }
+    /** Szint-sértés → `FAM-CONFIG-SET-005` (a kulcs nem értelmezett a kért level-en / tableOnly). */
+    validateLevel(key, entry, options) {
+        if (!entry.levels.includes(options.level)) {
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setLevelViolation, `Config '${key}' nem értelmezett a(z) '${options.level}' szinten. Megengedett: ${entry.levels.join(', ')}.`, options.issuer);
+        }
+        if ((options.level === fam_config_level_type_enum_1.FAM_ConfigLevel.table || options.level === fam_config_level_type_enum_1.FAM_ConfigLevel.scope) && !options.tableScope) {
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setLevelViolation, `Config '${key}' '${options.level}' szintű beállításához kötelező a tableScope.`, options.issuer);
+        }
+        if (entry.tableOnly && options.tableScope && options.tableScope !== entry.tableOnly) {
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setLevelViolation, `Config '${key}' CSAK a(z) '${entry.tableOnly}' táron állítható (kapott: '${options.tableScope}').`, options.issuer);
+        }
+    }
+    /** Típus-eltérés → `FAM-CONFIG-SET-002`. */
+    validateType(key, entry, value) {
+        const fail = (expected) => {
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setTypeMismatch, `Config '${key}' várt típusa '${expected}', kapott: '${this.typeOf(value)}'.`);
+        };
+        switch (entry.type) {
+            case 'number':
+                if (typeof value !== 'number' || Number.isNaN(value)) {
+                    fail('number');
+                }
+                break;
+            case 'number-or-null':
+                if (value !== null && (typeof value !== 'number' || Number.isNaN(value))) {
+                    fail('number | null');
+                }
+                break;
+            case 'string':
+                if (typeof value !== 'string') {
+                    fail('string');
+                }
+                break;
+            case 'boolean':
+                if (typeof value !== 'boolean') {
+                    fail('boolean');
+                }
+                break;
+            case 'string[]':
+                if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+                    fail('string[]');
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    /** Tartomány-/enum-sértés → `FAM-CONFIG-SET-003`. */
+    validateRange(key, entry, value) {
+        // number / number-or-null tartomány + integer.
+        if ((entry.type === 'number' || entry.type === 'number-or-null') && typeof value === 'number') {
+            if (entry.integer && !Number.isInteger(value)) {
+                throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setRangeViolation, `Config '${key}' egész számot vár (kapott tört: ${value}).`);
+            }
+            if (entry.min !== undefined && value < entry.min) {
+                throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setRangeViolation, `Config '${key}' minimum ${entry.min} (kapott: ${value}).`);
+            }
+            if (entry.max !== undefined && value > entry.max) {
+                throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setRangeViolation, `Config '${key}' maximum ${entry.max} (kapott: ${value}).`);
+            }
+        }
+        // string enum.
+        if (entry.type === 'string' && entry.enumValues && typeof value === 'string' && !entry.enumValues.includes(value)) {
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setRangeViolation, `Config '${key}' megengedett értékei: ${entry.enumValues.join(' | ')} (kapott: '${value}').`);
+        }
+    }
+    /**
+     * Cross-field invariáns (dsgn-007 §7.1, `FAM-CONFIG-SET-004`) a feloldott kontextusban:
+     * `read.topK <= read.maxResults`, minden `chunk.*.overlap < chunk.*.maxSize`,
+     * `embedding.costWarnUsd <= embedding.costCapUsd` (ha mindkettő adott). A "másik" mező a hozzá
+     * tartozó kontextuson feloldva (a most beállítandó értéket az adott kulcsra behelyettesítve).
+     */
+    async validateCrossField(key, value, options) {
+        const context = {
+            table: options.tableScope,
+            scopePath: options.scopeId ? [{ scopeId: options.scopeId, layer: '', canonicalName: '' }] : undefined,
+        };
+        const resolvedNumber = async (otherKey) => {
+            const resolved = await this.resolve(otherKey, context);
+            return typeof resolved.value === 'number' ? resolved.value : null;
+        };
+        // read.topK <= read.maxResults
+        if (key === 'read.topK' && typeof value === 'number') {
+            const maxResults = await resolvedNumber('read.maxResults');
+            if (maxResults !== null && value > maxResults) {
+                throw this.crossFieldError(`read.topK (${value}) nem haladhatja meg a read.maxResults-t (${maxResults}).`, options);
+            }
+        }
+        if (key === 'read.maxResults' && typeof value === 'number') {
+            const topK = await resolvedNumber('read.topK');
+            if (topK !== null && topK > value) {
+                throw this.crossFieldError(`read.maxResults (${value}) nem lehet kisebb a read.topK-nál (${topK}).`, options);
+            }
+        }
+        // chunk.*.overlap < chunk.*.maxSize
+        const overlapMatch = /^chunk\.(ts|md|generic)\.overlap$/.exec(key);
+        if (overlapMatch && typeof value === 'number') {
+            const maxSizeKey = `chunk.${overlapMatch[1]}.maxSize`;
+            const maxSize = await resolvedNumber(maxSizeKey);
+            if (maxSize !== null && value >= maxSize) {
+                throw this.crossFieldError(`${key} (${value}) kisebb kell legyen, mint ${maxSizeKey} (${maxSize}).`, options);
+            }
+        }
+        const maxSizeMatch = /^chunk\.(ts|md|generic)\.maxSize$/.exec(key);
+        if (maxSizeMatch && typeof value === 'number') {
+            const overlapKey = `chunk.${maxSizeMatch[1]}.overlap`;
+            const overlap = await resolvedNumber(overlapKey);
+            if (overlap !== null && overlap >= value) {
+                throw this.crossFieldError(`${key} (${value}) nagyobb kell legyen, mint ${overlapKey} (${overlap}).`, options);
+            }
+        }
+        // embedding.costWarnUsd <= embedding.costCapUsd
+        if (key === 'embedding.costWarnUsd' && typeof value === 'number') {
+            const cap = await resolvedNumber('embedding.costCapUsd');
+            if (cap !== null && value > cap) {
+                throw this.crossFieldError(`embedding.costWarnUsd (${value}) nem haladhatja meg a costCapUsd-t (${cap}).`, options);
+            }
+        }
+        if (key === 'embedding.costCapUsd' && typeof value === 'number') {
+            const warn = await resolvedNumber('embedding.costWarnUsd');
+            if (warn !== null && warn > value) {
+                throw this.crossFieldError(`embedding.costCapUsd (${value}) nem lehet kisebb a costWarnUsd-nál (${warn}).`, options);
+            }
+        }
+    }
+    crossFieldError(message, options) {
+        return this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.setCrossFieldViolation, `Cross-field invariáns sérült: ${message}`, options.issuer);
+    }
+    // =========================================================================
+    // PRESETS (dsgn-007 §5) — atomikus, validált, auditált apply
+    // =========================================================================
+    /**
+     * Egy beépített preset alkalmazása egy szintre (dsgn-007 §5). A preset minden kulcsa ELŐBB átmegy
+     * a `set`-validáción (atomikus: egyetlen invalid kulcs → az egész apply elutasítva, egy kulcs sem
+     * íródik); majd minden kulcs `set`-en át íródik (`setBy='preset'`, `setByDetail=<presetNév>`).
+     * Idempotens: újra-apply felülír; a preseten kívüli kulcsokat nem törli.
+     */
+    async applyPreset(name, target) {
+        const bundle = config_presets_const_1.CONFIG_PRESETS[name];
+        if (!bundle) {
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.preset, `Ismeretlen embedding-preset: '${name}'. Elérhető: ${Object.keys(config_presets_const_1.CONFIG_PRESETS).join(', ')}.`, target.issuer);
+        }
+        const level = target.scopeId ? fam_config_level_type_enum_1.FAM_ConfigLevel.scope : fam_config_level_type_enum_1.FAM_ConfigLevel.table;
+        if (level === fam_config_level_type_enum_1.FAM_ConfigLevel.table && !target.table) {
+            throw this.error(config_error_codes_const_1.FAM_CONFIG_ERROR_CODES.preset, `A preset '${name}' alkalmazásához table vagy scopeId kötelező.`, target.issuer);
+        }
+        const baseOptions = {
+            level: level,
+            tableScope: target.table,
+            scopeId: target.scopeId,
+            setBy: 'preset',
+            setByDetail: name,
+            issuer: target.issuer ?? this.issuer,
+        };
+        const entries = Object.entries(bundle);
+        // Atomikus: ELŐBB minden kulcsot validálunk (egy bukás → semmit nem írunk).
+        for (const [key, value] of entries) {
+            await this.validate(key, value, baseOptions);
+        }
+        // Majd minden kulcsot kiírunk (a `set` újra-validál; a már validált halmaz konzisztens).
+        const written = [];
+        for (const [key, value] of entries) {
+            written.push(await this.set(key, value, baseOptions));
+        }
+        return written;
+    }
+    // =========================================================================
+    // HISTORY (dsgn-007 §7.2) — felülírás-history (soft-delete-elt régi rekordok)
+    // =========================================================================
+    /**
+     * Egy feloldási-kulcs felülírás-historyja (dsgn-007 §7.2): a soft-delete-elt (archív) régi rekordok
+     * az archív collection-ből (`DyNTS_ArchiveDataService`). Audit-trail / rollback-alap.
+     */
+    async getHistory(key, options) {
+        const filter = this.levelKeyFilter(key, options);
+        const dataService = new config_data_service_1.FAM_Config_DataService({ issuer: options.issuer ?? this.issuer });
+        const archive_DS = dataService.getArchiveDataService();
+        return archive_DS.findDataList(filter, true);
+    }
+    // =========================================================================
+    // ENV SEED (dsgn-007 §6) — boot-hook; titok SOHA nem kerül DB-be
+    // =========================================================================
+    /**
+     * ENV → global default seed (dsgn-007 §6). Ha `fam_config` egy kulcsra üres, az
+     * `OPENAI_EMBEDDING_MODEL` / `EMBEDDING_PROVIDER` ENV-ből GLOBAL default-ot seedel
+     * (`setBy='env-seed'`). A titok (`OPENAI_API_KEY`, `LMSTUDIO_BASE_URL`) SOHA nem kerül DB-be;
+     * a többi default a `CONFIG_CATALOG` builtin-jéből jön (nincs szükség DB-rekordra). Egyszeri:
+     * csak hiányzó kulcsra ír, a runtime-szerkesztés felülírja és többé nem írja vissza.
+     */
+    async seedDefaultsFromEnv() {
+        const provider = process.env.EMBEDDING_PROVIDER;
+        // Provider-aware model-env: lmstudio (DEFAULT) → LMSTUDIO_EMBEDDING_MODEL; openai → OPENAI_EMBEDDING_MODEL.
+        const model = provider === 'lmstudio'
+            ? (process.env.LMSTUDIO_EMBEDDING_MODEL || process.env.EMBEDDING_MODEL)
+            : (process.env.OPENAI_EMBEDDING_MODEL || process.env.EMBEDDING_MODEL);
+        if (provider) {
+            await this.seedGlobalIfMissing('embedding.provider', provider);
+        }
+        if (model) {
+            await this.seedGlobalIfMissing('embedding.model', model);
+        }
+    }
+    /** Egy global kulcsot seedel, ha még NINCS aktív rekord rá (env-seed; dsgn-007 §6). */
+    async seedGlobalIfMissing(key, value) {
+        const dataService = new config_data_service_1.FAM_Config_DataService({ issuer: this.issuer });
+        const existing = await dataService.findActive({ level: fam_config_level_type_enum_1.FAM_ConfigLevel.global, key: key });
+        if (existing && existing._id) {
+            return;
+        }
+        await this.set(key, value, { level: fam_config_level_type_enum_1.FAM_ConfigLevel.global, setBy: 'env-seed', issuer: this.issuer });
+    }
+    // =========================================================================
+    // helpers
+    // =========================================================================
+    /** A teljes katalógus-kulcs lista (típusosan). */
+    allKeys() {
+        return Object.keys(config_catalog_const_1.CONFIG_CATALOG);
+    }
+    /** Egyszerű hasonló-kulcs javaslat (prefix-egyezés) az ismeretlen-kulcs hibához. */
+    similarKeys(key) {
+        const prefix = key.split('.')[0];
+        return this.allKeys().filter((known) => known.startsWith(prefix)).slice(0, 5);
+    }
+    /** Olvasható típus-jelölés a hiba-üzenethez. */
+    typeOf(value) {
+        if (value === null) {
+            return 'null';
+        }
+        if (Array.isArray(value)) {
+            return 'array';
+        }
+        return typeof value;
+    }
+    /** Strukturált config-hiba (a központi error-rétegnek; `level=error`, dsgn-008). */
+    error(errorCode, message, issuer) {
+        return new fsm_dynamo_1.DyFM_Error({
+            errorCode: errorCode,
+            message: message,
+            level: fsm_dynamo_1.DyFM_ErrorLevel.error,
+            issuer: issuer ?? this.issuer,
+            issuerService: this.issuer,
+        });
+    }
+}
+exports.FAM_Config_ControlService = FAM_Config_ControlService;