@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/scope-reference/_services/fam-scope.data-service.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Scope_DataService = void 0;
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_scope_data_model_1 = require("../../../_models/data-models/fam-scope.data-model");
+const fam_scope_normalize_util_1 = require("../_collections/fam-scope-normalize.util");
+/** A scope-böngészés CCAP-örökség konstansai (dsgn-007 §4 grounding). */
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 500;
+/** A parent-lánc ciklus-/mélység-védelem felső korlátja (SP-3.1 guard). */
+const MAX_SCOPE_DEPTH = 64;
+/**
+ * `FAM_Scope_DataService` (SP-3.1, dsgn-002 §2/§6) — a `fam_scopes` (MAIN) collection CRUD + a scope-fa
+ * traverzál-API. `extends DyNTS_DataService` (soft-delete = move-to-archive a `getArchiveDataService`-en
+ * át): a törölt scope NEM jelenik meg a traverzálban (a `findDataList` az aktívakat adja).
+ *
+ * **Determinizmus (dsgn-002 §7.6):** ugyanaz a canonical entitás (normalizált név + layer +
+ * parentScopeId) ugyanahhoz a `scopeId`-hoz vezet — a `findOrCreateScope` find-by-key fast-path
+ * MIELŐTT létrehozna (nincs duplikált fa-csúcs).
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** a base-ctor EAGER `getDBService`-t hív,
+ * ezért a control-service-ek NEM tartanak élő példányt mezőként — minden művelet előtt lazy `new`.
+ */
+class FAM_Scope_DataService extends nts_dynamo_1.DyNTS_DataService {
+    constructor(set) {
+        super(set.data instanceof fam_scope_data_model_1.FAM_Scope_DataModel ? set.data : new fam_scope_data_model_1.FAM_Scope_DataModel(set.data), fam_scope_data_model_1.famScope_dataParams, set.issuer);
+    }
+    /**
+     * A move-to-archive soft-delete (dsgn-001 §8) archív-collection service-e: a base `deleteData`
+     * (addArchive) ezt hívja, hogy a törölt scope-ot a `fam_scopes_archived` tárba mozgassa. A
+     * `DyNTS_DataService` base default-ja DOB (nincs ökoszisztéma-implementáció) — ezért az explicit
+     * override (a `DyNTS_ArchiveDataService` a `dataParams.addArchive`-ból oldja az archív-nevet).
+     */
+    getArchiveDataService() {
+        return new nts_dynamo_1.DyNTS_ArchiveDataService(new fam_scope_data_model_1.FAM_Scope_DataModel(), this.dataParams, this.issuer);
+    }
+    // =========================================================================
+    // CRUD + alap-lekérdezés (dsgn-002 §6)
+    // =========================================================================
+    /** Egy aktív scope `_id` alapján (vagy üres-objektum, ha nincs / törölt). */
+    async findScopeById(scopeId) {
+        return this.findData({ _id: scopeId }, true);
+    }
+    /** Egy layer összes aktív scope-ja (a böngészéshez / determinizmus-feloldáshoz). */
+    async findByLayer(layer) {
+        return this.findDataList({ layer: layer }, true);
+    }
+    /**
+     * `findByCanonical(layer, name)` (SP-3.1) — egy layer azon aktív scope-jai, amelyek
+     * canonical-neve NORMALIZÁLT-egyezik a megadott névvel. A Mongo-szűrés a layerre megy
+     * (nincs normalizált-mező a sémában), a normalizált-egyezést memóriában szűrjük (a scope-halmaz
+     * kicsi). A `parentScopeId` opcionális szűkítés (azonos név más ágon külön entitás lehet).
+     */
+    async findByCanonical(layer, name, parentScopeId) {
+        const layerScopes = await this.findByLayer(layer);
+        const targetKey = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(name);
+        return layerScopes.filter((scope) => {
+            const nameMatch = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(scope.canonicalName) === targetKey;
+            const parentMatch = parentScopeId === undefined || scope.parentScopeId === parentScopeId;
+            return nameMatch && parentMatch;
+        });
+    }
+    /** Egy scope közvetlen (aktív) gyerekei (a subtree-traverzál egy lépése). */
+    async findChildren(parentScopeId) {
+        return this.findDataList({ parentScopeId: parentScopeId }, true);
+    }
+    /** Minden aktív scope (a scope-fa in-memory bejárásához; a halmaz kicsi). */
+    async findAllActive() {
+        return this.findDataList({}, true);
+    }
+    /**
+     * `listScopes` (SP-3.1) — lapozott scope-lista az UI/CLI böngészéshez. A `pageSize` a
+     * `MAX_PAGE_SIZE`-ra kapozott; a lapozás memóriában (a scope-halmaz kicsi, a determinizmus a
+     * fontos, nem a DB-paging). `layer`/`parentScopeId` opcionális szűrés.
+     */
+    async listScopes(input) {
+        const filter = {};
+        if (input.layer) {
+            filter.layer = input.layer;
+        }
+        if (input.parentScopeId) {
+            filter.parentScopeId = input.parentScopeId;
+        }
+        const all = await this.findDataList(filter, true);
+        const pageSize = Math.min(input.pageSize ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE);
+        const page = input.page && input.page > 0 ? input.page : 1;
+        const start = (page - 1) * pageSize;
+        return all.slice(start, start + pageSize);
+    }
+    // =========================================================================
+    // SCOPE-FA TRAVERZÁL (dsgn-002 §2/§6, SP-3.1)
+    // =========================================================================
+    /**
+     * `buildScopePath(scopeId)` (SP-3.1) — parent-lánc traverzál: a `parentScopeId`-n FELFELÉ a
+     * gyökérig, majd root→leaf rendezve `FAM_ScopeRef[]`-re map-elve. Ciklus-/mélység-védelem:
+     * `MAX_SCOPE_DEPTH` lépés VAGY már-látott scopeId → `FAM-REF-INDEX-001` (NEM végtelen ciklus).
+     * Hiányzó/törölt scope a láncban → a lánc ott megszakad (a meglévő prefix visszaadva).
+     */
+    async buildScopePath(scopeId) {
+        const chain = [];
+        const seen = new Set();
+        let currentId = scopeId;
+        let depth = 0;
+        while (currentId) {
+            if (seen.has(currentId)) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.refIndexRebuild,
+                    message: `Ciklikus parent-referencia a scope-fában (scopeId '${currentId}' már szerepelt a láncban). `
+                        + 'A scope-fa hibás — a parent-lánc nem zárható le.',
+                    issuer: this.issuer,
+                    context: { operation: 'build-scope-path' },
+                });
+            }
+            if (depth >= MAX_SCOPE_DEPTH) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.refIndexRebuild,
+                    message: `A scope parent-lánc meghaladta a maximális mélységet (${MAX_SCOPE_DEPTH}) — `
+                        + 'valószínűleg hibás parent-referencia. A lánc nem zárható le.',
+                    issuer: this.issuer,
+                    context: { operation: 'build-scope-path' },
+                });
+            }
+            seen.add(currentId);
+            depth++;
+            const scope = await this.findScopeById(currentId);
+            if (!scope || !scope._id) {
+                break;
+            }
+            // A láncot leaf→root építjük, a végén megfordítjuk root→leaf-re.
+            chain.push({
+                scopeId: scope._id,
+                layer: scope.layer ?? '',
+                canonicalName: scope.canonicalName ?? '',
+            });
+            currentId = scope.parentScopeId;
+        }
+        return chain.reverse();
+    }
+    /**
+     * `getSubtreeScopeIds(scopeId)` (SP-3.1) — a megadott scope + ÖSSZES (aktív) leszármazott
+     * `scopeId`-ja (subtree-match, dsgn-002 §3.3). Egyetlen aktív-snapshot olvasás + in-memory
+     * parent→children BFS (nincs N+1 query; a scope-halmaz kicsi). A testvér-ágakat NEM tartalmazza.
+     * Ciklus-védelem: már-látott scopeId-t nem jár be újra.
+     */
+    async getSubtreeScopeIds(scopeId) {
+        const all = await this.findAllActive();
+        // parent → gyerek-ID-k index (egyetlen passz; in-memory fa).
+        const childrenByParent = new Map();
+        for (const scope of all) {
+            if (!scope._id) {
+                continue;
+            }
+            const parent = scope.parentScopeId ?? '';
+            const bucket = childrenByParent.get(parent) ?? [];
+            bucket.push(scope._id);
+            childrenByParent.set(parent, bucket);
+        }
+        const result = [];
+        const seen = new Set();
+        const queue = [scopeId];
+        while (queue.length) {
+            const currentId = queue.shift();
+            if (seen.has(currentId)) {
+                continue;
+            }
+            seen.add(currentId);
+            result.push(currentId);
+            const children = childrenByParent.get(currentId) ?? [];
+            for (const childId of children) {
+                if (!seen.has(childId)) {
+                    queue.push(childId);
+                }
+            }
+        }
+        return result;
+    }
+    // =========================================================================
+    // DETERMINISZTIKUS DE-DUP (dsgn-002 §7.6, SP-3.1)
+    // =========================================================================
+    /**
+     * `findOrCreateScope` (SP-3.1) — determinisztikus scope-de-dup. Ha a (normalizált
+     * `canonicalName` + `layer` + `parentScopeId`) hármas már létezik AKTÍVAN → a meglévő `scopeId`;
+     * KÜLÖNBEN új entitás (`createdBy` a bemenetből). Ugyanazzal a hármassal kétszer hívva UGYANAZT
+     * a `scopeId`-t adja (nincs duplikált fa-csúcs — dsgn-002 §7.6). Az `_id`-t a Dynamo `saveData`
+     * generálja (a `find` MIELŐTT — ezért determinisztikus a feloldás, nem az `_id` maga).
+     */
+    async findOrCreateScope(input) {
+        const existing = await this.findByCanonical(input.layer, input.canonicalName, input.parentScopeId);
+        if (existing.length && existing[0]._id) {
+            return { scope: existing[0], created: false };
+        }
+        const record = new fam_scope_data_model_1.FAM_Scope_DataModel({
+            layer: input.layer,
+            canonicalName: input.canonicalName,
+            parentScopeId: input.parentScopeId,
+            description: input.description,
+            createdBy: input.createdBy,
+            aliases: [],
+        });
+        const writeService = new FAM_Scope_DataService({ data: record, issuer: this.issuer });
+        const saved = await writeService.saveData(record);
+        return { scope: saved, created: true };
+    }
+    /**
+     * Egy scope `aliases[]` denormalizált gyors-cache frissítése (`$set`, atomikus — a Mixed-szerű
+     * `string[]` silent-drop ellen; memory: reference_mongoose_mixed_atomic_write). A forrás a
+     * `fam_reference` (SP-3.2/SP-3.3 töltheti). NEM a teljes instance-en `saveData`-val.
+     */
+    async setAliases(scopeId, aliases) {
+        await this.updateData({ filterBy: { _id: scopeId }, update: { $set: { aliases: aliases } } });
+    }
+}
+exports.FAM_Scope_DataService = FAM_Scope_DataService;

package/build/src/_modules/scope-reference/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * `scope-reference` modul barrel (MP-3, dsgn-002) — a scope/reference feloldó-engine publikus
+ * felülete. A fogyasztó-MP-k innen importálnak: a WRITE-path (MP-6) a `resolveForWrite`-ot, a
+ * READ prefilter (MP-5) az `expandForRead`-et, a `rebuild_reference_index`/`trace_*` capability
+ * (MP-6) a `rebuildReferenceIndex`/`traceResolution`-t, az MP-7 config-set a `scopeExists`-et hívja.
+ *
+ * Boundary (dsgn-002 §6): MP-3 = a feloldó-ENGINE; a write/read wiring + capability-regisztráció
+ * a fogyasztó-MP-ké. A reference/scope collection-ök MP-1-ben már a `dbModels`-ben vannak.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_FuzzyMatch_Util = exports.FAM_ScopeNormalize_Util = exports.FAM_ScopeResolver_ControlService = exports.FAM_Reference_DataService = exports.FAM_Scope_DataService = void 0;
+// SP-3.1 — Scope CRUD + scope-fa traverzál
+var fam_scope_data_service_1 = require("./_services/fam-scope.data-service");
+Object.defineProperty(exports, "FAM_Scope_DataService", { enumerable: true, get: function () { return fam_scope_data_service_1.FAM_Scope_DataService; } });
+// SP-3.2 — Reference CRUD + exact/string-fuzzy/vektor-fuzzy
+var fam_reference_data_service_1 = require("./_services/fam-reference.data-service");
+Object.defineProperty(exports, "FAM_Reference_DataService", { enumerable: true, get: function () { return fam_reference_data_service_1.FAM_Reference_DataService; } });
+// SP-3.3/SP-3.4 — a feloldó control-service (write-resolve / read-expand / cache / scopeExists / uncertainty)
+var fam_scope_resolver_control_service_1 = require("./_services/fam-scope-resolver.control-service");
+Object.defineProperty(exports, "FAM_ScopeResolver_ControlService", { enumerable: true, get: function () { return fam_scope_resolver_control_service_1.FAM_ScopeResolver_ControlService; } });
+// utils (SP-3.1/SP-3.2)
+var fam_scope_normalize_util_1 = require("./_collections/fam-scope-normalize.util");
+Object.defineProperty(exports, "FAM_ScopeNormalize_Util", { enumerable: true, get: function () { return fam_scope_normalize_util_1.FAM_ScopeNormalize_Util; } });
+var fam_fuzzy_match_util_1 = require("./_collections/fam-fuzzy-match.util");
+Object.defineProperty(exports, "FAM_FuzzyMatch_Util", { enumerable: true, get: function () { return fam_fuzzy_match_util_1.FAM_FuzzyMatch_Util; } });

package/build/src/_routes/server/api/api.controller.js

@@ -0,0 +1,400 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Api_Controller = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const fam_config_level_type_enum_1 = require("../../../_enums/fam-config-level.type-enum");
+const config_control_service_1 = require("../config/config.control-service");
+const embedding_1 = require("../../../_modules/embedding");
+const ingest_1 = require("../../../_modules/ingest");
+const mcp_1 = require("../../../_modules/mcp");
+/** A UI/CLI lapozás CCAP-örökség konstansai (dsgn-010/dsgn-011 §4.1). */
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 500;
+/** A 6 fő RAG-tár (a `/stats` + `/items` REST-hez). */
+const MAIN_TABLES = [
+    fam_table_type_enum_1.FAM_Table.rules, fam_table_type_enum_1.FAM_Table.documents, fam_table_type_enum_1.FAM_Table.codebase,
+    fam_table_type_enum_1.FAM_Table.knowledge, fam_table_type_enum_1.FAM_Table.codingPatterns, fam_table_type_enum_1.FAM_Table.memory,
+];
+/**
+ * `Api_Controller` (SP-6.5, dsgn-010 §9 / dsgn-011 §2) — a CLI (MP-9) + UI (MP-10) közös szerver-
+ * belépési pontja: a 3 core-tool **REST-tükre** + a UI-specifikus listázó/stat/ingest endpoint-ok.
+ * A REST-handler UGYANAZT a transport-agnosztikus core-service-t hívja, mint az MCP-réteg
+ * (`FAM_ReadTool_Service`/`FAM_WriteTool_Service`/`FAM_CapabilitiesTool_Service`) — paritás-garancia,
+ * no-duplication (dsgn-003 §6.5). No-auth, lokál, port 39185 (ADR-004).
+ *
+ * **Endpoint-felület (a kód-szintű kontraktus — a formális `__documentations/server-api.md` follow-up;
+ * dsgn-013 user-jóváhagyásra vár):** lásd a modul `README.md`-jét.
+ *   POST /read · POST /write · POST /capabilities  — a dsgn-003 §2/§3/§4 mirror
+ *   GET  /health                                    — CLI remote reachability-check (dsgn-010 §9)
+ *   GET  /items/:table                              — lapozható/szűrhető elem-lista (dsgn-011 §4.1)
+ *   GET  /stats · GET /stats/:table                 — high-level stats aggregátum (dsgn-011 §3/§4.4)
+ *   GET  /ingest-runs                               — ingest-run idővonal (dsgn-011 §7)
+ *
+ * **Hiba-fordítás (dsgn-008, néma hiba tilos):** minden handler-hiba strukturált REST-hibatestté
+ * (`{ ok:false, error:{ errorCode, message } }`) fordul, megfelelő HTTP-státusszal — a UI banner /
+ * CLI exit-kód köthető. Singleton: `getInstance()` → `getSingletonInstance()`.
+ */
+class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
+    static getInstance() {
+        return Api_Controller.getSingletonInstance();
+    }
+    /** Default issuer (a REST-réteg hibáihoz; dsgn-008). */
+    issuer = 'Api_Controller';
+    setupEndpoints() {
+        this.endpoints = [
+            this.rootRedirectEndpoint(),
+            this.readEndpoint(),
+            this.writeEndpoint(),
+            this.capabilitiesEndpoint(),
+            this.healthEndpoint(),
+            this.itemsEndpoint(),
+            this.statsEndpoint(),
+            this.statsTableEndpoint(),
+            this.ingestRunsEndpoint(),
+            this.configGetEndpoint(),
+            this.configSetEndpoint(),
+        ];
+    }
+    // =========================================================================
+    // /  (→ /api/) — az API-gyökér átirányít a beépített admin-UI-ra
+    // =========================================================================
+    /** `GET /api/` — a felhasználót a beépített Angular admin-UI-ra (`/api/app/`) irányítja (UX). */
+    rootRedirectEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'rootRedirect',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/',
+            tasks: [
+                async (_req, res) => {
+                    res.redirect(302, '/api/app/');
+                },
+            ],
+        });
+    }
+    // =========================================================================
+    // core-mirror: /read · /write · /capabilities (dsgn-003 §2/§3/§4)
+    // =========================================================================
+    /** `POST /read` — a dsgn-003 §2 input → §2.2 output (a MCP `read` tool REST-tükre). */
+    readEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'read',
+            type: fsm_dynamo_1.DyFM_HttpCallType.post,
+            endpoint: '/read',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const input = (req.body ?? {});
+                        return mcp_1.FAM_ReadTool_Service.getInstance().handle(input);
+                    });
+                },
+            ],
+        });
+    }
+    /** `POST /write` — a dsgn-003 §3 input → §3.2 output (a MCP `write` tool REST-tükre). */
+    writeEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'write',
+            type: fsm_dynamo_1.DyFM_HttpCallType.post,
+            endpoint: '/write',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const input = (req.body ?? {});
+                        return mcp_1.FAM_WriteTool_Service.getInstance().handle(input);
+                    });
+                },
+            ],
+        });
+    }
+    /** `POST /capabilities` — a dsgn-003 §4 action input → output (list/describe/invoke REST-tükre). */
+    capabilitiesEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'capabilities',
+            type: fsm_dynamo_1.DyFM_HttpCallType.post,
+            endpoint: '/capabilities',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const input = (req.body ?? {});
+                        return mcp_1.FAM_CapabilitiesTool_Service.getInstance().handle(input);
+                    });
+                },
+            ],
+        });
+    }
+    // =========================================================================
+    // /health — CLI remote reachability-check (dsgn-010 §9)
+    // =========================================================================
+    /** `GET /health` — a CLI `--server-url` elérhetőség-próbája (dsgn-010 §9). */
+    healthEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'health',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/health',
+            tasks: [
+                async (req, res) => {
+                    res.send({ ok: true, service: 'fdp-agent-memory', uptime: process.uptime() });
+                },
+            ],
+        });
+    }
+    // =========================================================================
+    // /items/:table — lapozható/szűrhető elem-lista (dsgn-011 §4.1)
+    // =========================================================================
+    /**
+     * `GET /items/:table` — egy tár lapozható/szűrhető elem-listája (a UI table-detail; dsgn-011 §4.1).
+     * Query: `page`/`pageSize` (cap 500), `tag`/`kind`/`ingestRunId` szűrő. A scope-szűrés a UI-n a
+     * `read`/capability-n megy (itt sima substring/mező-szűrő, NEM vektor).
+     */
+    itemsEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'items',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/items/:table',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => this.listItems(req));
+                },
+            ],
+        });
+    }
+    /** A `/items/:table` adat-oldali lekérdezése (lapozott + szűrt). */
+    async listItems(req) {
+        const table = this.parseTable(req.params.table);
+        const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(table);
+        if (!registryEntry) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'FAM-VAL-READ-001',
+                message: `A(z) '${req.params.table}' nem fő RAG-tár (a 6 fő tár egyike szükséges).`,
+                issuer: this.issuer,
+            });
+        }
+        const filter = {};
+        if (req.query.kind) {
+            filter.kind = String(req.query.kind);
+        }
+        if (req.query.tag) {
+            filter.tags = String(req.query.tag);
+        }
+        if (req.query.ingestRunId) {
+            filter.ingestRunId = String(req.query.ingestRunId);
+        }
+        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const all = await dataService.findHydratableList(filter);
+        const pageSize = Math.min(this.parseNumber(req.query.pageSize, DEFAULT_PAGE_SIZE), MAX_PAGE_SIZE);
+        const page = Math.max(this.parseNumber(req.query.page, 1), 1);
+        const start = (page - 1) * pageSize;
+        const items = all.slice(start, start + pageSize);
+        return { table: table, total: all.length, page: page, pageSize: pageSize, items: items };
+    }
+    // =========================================================================
+    // /stats · /stats/:table — high-level stats aggregátum (dsgn-011 §3/§4.4)
+    // =========================================================================
+    /** `GET /stats` — minden fő tár stats-aggregátuma (a UI landing; dsgn-011 §3). */
+    statsEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'stats',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/stats',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => ({ tables: await this.collectTableStats(MAIN_TABLES) }));
+                },
+            ],
+        });
+    }
+    /** `GET /stats/:table` — egy tár részletes stats-a (a UI table-detail; dsgn-011 §4.4). */
+    statsTableEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'statsTable',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/stats/:table',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const table = this.parseTable(req.params.table);
+                        const stats = await this.collectTableStats([table]);
+                        return stats[0] ?? { table: table, count: 0 };
+                    });
+                },
+            ],
+        });
+    }
+    /** A tár-stats aggregátum (aktív elem-szám + embedding-státusz + utolsó ingest) — dsgn-011 §3/§4.4. */
+    async collectTableStats(tables) {
+        const result = [];
+        for (const table of tables) {
+            const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(table);
+            if (!registryEntry) {
+                continue;
+            }
+            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+            const entries = await dataService.findHydratableList({});
+            const byStatus = { pending: 0, completed: 0, error: 0 };
+            let lastModifiedMs = 0;
+            for (const entry of entries) {
+                const status = entry.embeddingStatus ?? 'pending';
+                byStatus[status] = (byStatus[status] ?? 0) + 1;
+                const modified = entry.__lastModified ? new Date(entry.__lastModified).getTime() : 0;
+                if (modified > lastModifiedMs) {
+                    lastModifiedMs = modified;
+                }
+            }
+            result.push({
+                table: table,
+                count: entries.length,
+                embeddingStatus: byStatus,
+                lastModified: lastModifiedMs ? new Date(lastModifiedMs).toISOString() : null,
+                status: entries.length ? 'ok' : 'empty',
+            });
+        }
+        return result;
+    }
+    // =========================================================================
+    // /ingest-runs — ingest-run idővonal (dsgn-011 §7)
+    // =========================================================================
+    /** `GET /ingest-runs` — az ingest-run-ok listája (a UI idővonal; `?table=` szűrővel). */
+    ingestRunsEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'ingestRuns',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/ingest-runs',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const runDataService = new ingest_1.FAM_IngestRun_DataService({ issuer: this.issuer });
+                        const runs = await runDataService.listRuns();
+                        const tableFilter = req.query.table ? String(req.query.table) : undefined;
+                        const filtered = tableFilter
+                            ? runs.filter((run) => this.runHasTable(run.table, tableFilter))
+                            : runs;
+                        return { runs: filtered };
+                    });
+                },
+            ],
+        });
+    }
+    /** Egy run érinti-e az adott tárat (a `table` lehet egyetlen érték vagy tömb). */
+    runHasTable(runTable, table) {
+        if (!runTable) {
+            return false;
+        }
+        return Array.isArray(runTable) ? runTable.some((entry) => String(entry) === table) : String(runTable) === table;
+    }
+    // =========================================================================
+    // /config — scoped config olvasás/írás (dsgn-007; a UI settings + CLI config)
+    // =========================================================================
+    /**
+     * `GET /config` — a teljes effektív (merge-elt) config az adott kontextusra (`?table=`),
+     * a precedencia-forrással (global<table<scope; dsgn-007 §3). A `list_*`/config-capability REST-tükre.
+     */
+    configGetEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'configGet',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/config',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const table = req.query.table
+                            ? this.parseTable(String(req.query.table))
+                            : undefined;
+                        const effective = await config_control_service_1.FAM_Config_ControlService.getInstance().resolveAll({ table: table });
+                        return { table: table, effective: effective };
+                    });
+                },
+            ],
+        });
+    }
+    /**
+     * `PUT /config` — egy config-érték beállítása egy szinten (dsgn-007 §7). Body: `{ key, value,
+     * level?, table?, scopeId? }`. A `set` validál + soft-delete-eli a régit + invalidál (a UI settings
+     * + CLI `config set` REST-tükre). A validációs hiba strukturált REST-hibatest (dsgn-008).
+     */
+    configSetEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'configSet',
+            type: fsm_dynamo_1.DyFM_HttpCallType.put,
+            endpoint: '/config',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => this.setConfig(req));
+                },
+            ],
+        });
+    }
+    /** A `PUT /config` body-feldolgozása + `set` (dsgn-007 §7). */
+    async setConfig(req) {
+        const body = (req.body ?? {});
+        if (!body.key) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'FAM-VAL-WRITE-001',
+                message: 'A config-set `key`-t igényel (a CONFIG_CATALOG dotted kulcsa).',
+                issuer: this.issuer,
+            });
+        }
+        const level = body.scopeId
+            ? fam_config_level_type_enum_1.FAM_ConfigLevel.scope
+            : body.table
+                ? fam_config_level_type_enum_1.FAM_ConfigLevel.table
+                : fam_config_level_type_enum_1.FAM_ConfigLevel.global;
+        const options = {
+            level: level,
+            tableScope: body.table ? this.parseTable(body.table) : undefined,
+            scopeId: body.scopeId,
+            setBy: 'ui',
+        };
+        const saved = await config_control_service_1.FAM_Config_ControlService.getInstance()
+            .set(body.key, body.value, options);
+        return { ok: true, key: body.key, level: level, saved: saved };
+    }
+    // =========================================================================
+    // helpers — egységes hiba-fordítás (dsgn-008, néma hiba tilos)
+    // =========================================================================
+    /**
+     * Egy handler futtatása + egységes REST-hiba-fordítás (dsgn-008). A `DyFM_Error` → strukturált
+     * hibatest (`{ ok:false, error:{ errorCode, message } }`) HTTP 400-zal (user-level) / 500-zal;
+     * a sikeres eredmény nyers JSON-ként. A `globalErrorHandler` (App) a hibát persistálja is.
+     */
+    async run(res, handler) {
+        try {
+            const data = await handler();
+            res.send(data);
+        }
+        catch (error) {
+            const errorCode = error instanceof fsm_dynamo_1.DyFM_Error
+                ? (fsm_dynamo_1.DyFM_Error.getErrorCode(error) ?? 'FAM-MCP-DISPATCH-001')
+                : 'FAM-MCP-DISPATCH-001';
+            const message = error instanceof fsm_dynamo_1.DyFM_Error
+                ? (fsm_dynamo_1.DyFM_Error.getErrorMessage(error) || 'Ismeretlen FAM hiba.')
+                : (error instanceof Error ? error.message : 'Ismeretlen hiba.');
+            const status = this.httpStatusForCode(errorCode);
+            res.status(status).send({ ok: false, error: { errorCode: errorCode, message: message } });
+        }
+    }
+    /** A FAM hibakód → HTTP-státusz (a user/validation-hibák 400, a többi 500; dsgn-008). */
+    httpStatusForCode(errorCode) {
+        const userPrefixes = ['FAM-VAL-', 'FAM-REF-RESOLVE-', 'FAM-SCOPE-WRITE-', 'FAM-MCP-DISPATCH-'];
+        return userPrefixes.some((prefix) => errorCode.startsWith(prefix)) ? 400 : 500;
+    }
+    /** A `:table` path-param → `FAM_Table` (ismeretlen → hiba). */
+    parseTable(raw) {
+        const match = Object.values(fam_table_type_enum_1.FAM_Table).find((table) => table === raw);
+        if (!match) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'FAM-VAL-READ-001',
+                message: `Ismeretlen tár: '${raw}'. Megengedett: ${Object.values(fam_table_type_enum_1.FAM_Table).join(', ')}.`,
+                issuer: this.issuer,
+            });
+        }
+        return match;
+    }
+    /** Egy query-paraméter szám-ként (vagy a fallback). */
+    parseNumber(value, fallback) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : fallback;
+    }
+}
+exports.Api_Controller = Api_Controller;