@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/mcp/_services/fam-capability-registry.service.js

@@ -0,0 +1,1180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_CapabilityRegistry = void 0;
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const config_data_service_1 = require("../../../_routes/server/config/config.data-service");
+const errors_control_service_1 = require("../../../_routes/server/errors/errors.control-service");
+const embedding_1 = require("../../embedding");
+const ingest_1 = require("../../ingest");
+const retrieval_1 = require("../../retrieval");
+const migration_1 = require("../../migration");
+const scope_reference_1 = require("../../scope-reference");
+const fam_mcp_interface_1 = require("../_models/interfaces/fam-mcp.interface");
+/** A főtár-nevek a `list_tables` / `get_table_stats` capability-khez. */
+const MAIN_TABLES = embedding_1.FAM_STORE_REGISTRY.map((entry) => entry.table);
+/**
+ * `FAM_CapabilityRegistry` (SP-6.4, dsgn-003 §4.2) — a **discoverable speciális eszközök** belső
+ * registry-je. Singleton. A 6 kategória (config-diagnostics / high-level-stats / inspection /
+ * maintenance / import-migration / debug) minden eszköze ITT él (név + kategória + leírás + schema +
+ * handler), és **kizárólag** a `capabilities` tool-on át érhető el (`list`/`describe`/`invoke`).
+ *
+ * **Diszjunkció (dsgn-003 §6.6):** ezek az eszközök SOHA nem kerülnek a SDK advertised tool-listájába
+ * (a `read`/`write`/`capabilities` az egyetlen hirdetett halmaz). A registry a katalógus SINGLE
+ * SOURCE-a — a `list` ebből generál, a contract-teszt a dsgn-003 §4.2 nevekkel veti össze.
+ *
+ * **Delegálás (nem duplikálás):** minden handler a megfelelő upstream engine-re delegál (config: MP-7;
+ * stats: MP-1/MP-2/MP-3; inspection: MP-1/MP-3/MP-4/MP-8; maintenance: MP-2/MP-3; debug: MP-3).
+ * Az import/migration + néhány még-nem-épült engine handler **late-bind** (clear "pending MP-X" hiba az
+ * `invoke`-on; a `list`/`describe` ettől teljes).
+ */
+class FAM_CapabilityRegistry {
+    static _instance;
+    /** A capability-eszközök `name` → deszkriptor map-je (a single-source katalógus). */
+    registry = new Map();
+    /** Default issuer (a capability-hibák issuer-éhez; dsgn-008). */
+    issuer = 'FAM_CapabilityRegistry';
+    constructor() {
+        this.registerAll();
+    }
+    static getInstance() {
+        if (!FAM_CapabilityRegistry._instance) {
+            FAM_CapabilityRegistry._instance = new FAM_CapabilityRegistry();
+        }
+        return FAM_CapabilityRegistry._instance;
+    }
+    // =========================================================================
+    // Public registry API (a `capabilities` tool — SP-6.4 — fogyasztja)
+    // =========================================================================
+    /** Egy deszkriptor a nevéből (vagy undefined, ha ismeretlen). */
+    get(name) {
+        return this.registry.get(name);
+    }
+    /** A teljes katalógus (a `list` + a contract-teszt fogyasztja). */
+    list(category) {
+        const all = Array.from(this.registry.values());
+        return category ? all.filter((descriptor) => descriptor.category === category) : all;
+    }
+    /** A capability-nevek halmaza (a diszjunkció-teszthez: ezek SOHA nem advertised tool-ok). */
+    names() {
+        return Array.from(this.registry.keys());
+    }
+    // =========================================================================
+    // Katalógus-feltöltés (dsgn-003 §4.2 — 6 kategória)
+    // =========================================================================
+    /** A teljes dsgn-003 §4.2 katalógus regisztrálása (a registry single-source). */
+    registerAll() {
+        this.registerConfigDiagnostics();
+        this.registerHighLevelStats();
+        this.registerInspection();
+        this.registerMaintenance();
+        this.registerImportMigration();
+        this.registerDebug();
+    }
+    /** config / diagnostics → MP-7 (config) + MP-2 (embedding) + MP-0 (env/mongo). */
+    registerConfigDiagnostics() {
+        const category = fam_mcp_interface_1.FAM_CapabilityCategory.configDiagnostics;
+        this.register({
+            name: 'get_config_status', category: category,
+            description: 'A teljes effektív config egy adott kontextusra (table/scope), a precedencia-forrással '
+                + '(scope>table>global>builtin).',
+            inputSchema: this.objectSchema({
+                table: this.tableSchema(false),
+                scopePath: this.scopeLayerArraySchema(),
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                const ctx = await this.toConfigContext(input);
+                return this.ok(await config_control_service_1.FAM_Config_ControlService.getInstance().resolveAll(ctx));
+            },
+        });
+        this.register({
+            name: 'get_embedding_config', category: category,
+            description: 'A feloldott embedding-provider + modell + dimenzió + batch-méret az adott kontextusra.',
+            inputSchema: this.objectSchema({ table: this.tableSchema(false) }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                const probe = await embedding_1.FAM_Embedding_ControlService.getInstance()
+                    .testProvider({ table: this.optionalTable(input.table) });
+                return this.ok(probe.resolved);
+            },
+        });
+        this.register({
+            name: 'test_embedding_provider', category: category,
+            description: 'A jelenleg feloldott embedding-provider elérhetőség-próbája (available + resolved provider).',
+            inputSchema: this.objectSchema({ table: this.tableSchema(false) }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await embedding_1.FAM_Embedding_ControlService.getInstance()
+                    .testProvider({ table: this.optionalTable(input.table) }));
+            },
+        });
+        // validate_environment / test_mongodb_connection / test_vector_search (MP-12) — a doctor-réteg
+        // 3 infra-diag-je. A `fam doctor` env/mongodb/vector al-checkjei ezeket invokálják (dsgn-010 §5.2).
+        // NEM új diag-engine: az env a `process.env`-et olvassa, a Mongo a Dynamo DataService-en keresztül
+        // pingel, a vektor az MP-2 embedding + VectorSearch smoke-ját futtatja (REUSE).
+        this.register({
+            name: 'validate_environment', category: category,
+            description: 'Env-változók (MONGODB_URI / EMBEDDING_PROVIDER / OPENAI_API_KEY / LMSTUDIO_* …) jelenlét- '
+                + 'ellenőrzése provider-feltételes kötelezőséggel (doctor `env`, dsgn-012 §7.1).',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok(this.validateEnvironment()),
+        });
+        this.register({
+            name: 'test_mongodb_connection', category: category,
+            description: 'MongoDB-kapcsolat próbája: egy könnyű olvasás a `fam_config` collection-ön (doctor `mongodb`). '
+                + 'Sikertelen connect → FAM-DB-CONNECT-001 (nem néma).',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok(await this.testMongoConnection()),
+        });
+        this.register({
+            name: 'test_vector_search', category: category,
+            description: 'A Memory Vector Search pool hidratáltság-/keresés-próbája (doctor `vector`): egy próba-szöveg '
+                + 'embed-elése + koszinusz-keresés a tár pool-jában (LVS smoke; dsgn-006 §4).',
+            inputSchema: this.objectSchema({ table: this.tableSchema(false) }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await this.testVectorSearch(this.optionalTable(input.table)));
+            },
+        });
+    }
+    /** high-level stats → MP-1 (count) + MP-3 (scope/reference) + MP-2 (cost). */
+    registerHighLevelStats() {
+        const category = fam_mcp_interface_1.FAM_CapabilityCategory.highLevelStats;
+        this.register({
+            name: 'get_table_stats', category: category,
+            description: 'Per-tár statisztika: aktív elem-szám, embedding-státusz bontás (pending/completed/error).',
+            inputSchema: this.objectSchema({ table: this.tableSchema(false) }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await this.tableStats(this.optionalTable(input.table)));
+            },
+        });
+        this.register({
+            name: 'get_scope_tree', category: category,
+            description: 'A teljes scope-fa (root→leaf hierarchia, layer + canonical-név + parent).',
+            inputSchema: this.objectSchema({}),
+            handler: async () => {
+                const scope_DS = new scope_reference_1.FAM_Scope_DataService({ issuer: this.issuer });
+                const all = await scope_DS.findAllActive();
+                return this.ok(all.map((scope) => ({
+                    scopeId: scope._id, layer: scope.layer, canonicalName: scope.canonicalName,
+                    parentScopeId: scope.parentScopeId, aliases: scope.aliases ?? [],
+                })));
+            },
+        });
+        this.register({
+            name: 'get_reference_stats', category: category,
+            description: 'A reference helper-tár statisztikája: aktív bejegyzés-szám.',
+            inputSchema: this.objectSchema({}),
+            handler: async () => {
+                const reference_DS = new scope_reference_1.FAM_Reference_DataService({ issuer: this.issuer });
+                const active = await reference_DS.findActive();
+                return this.ok({ activeReferences: active.length });
+            },
+        });
+        this.register({
+            name: 'get_embedding_cost_stats', category: category,
+            description: 'Az aktuális process-futás embedding-költség aggregátuma hívás-típusonként (BFR-AM-007).',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok(embedding_1.FAM_EmbeddingCost_ControlService.getInstance().getStats()),
+        });
+        // get_layer_stats / get_storage_usage (MP-12) — a stats-réteg aggregátum-bővítése. A layer-stats
+        // a scope-fát layerenként összesíti (MP-3), a storage-usage a fő + helper collection-ök aktív
+        // doc-számát adja (MP-1) — collection-méret-becslés (a Dynamo base nincs natív count, ezért aktív-szám).
+        this.register({
+            name: 'get_layer_stats', category: category,
+            description: 'Layer-szintű scope-aggregátum (layer → scope-szám + root/child bontás). A scope-fát '
+                + 'layerenként összesíti (MP-3).',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok(await this.layerStats()),
+        });
+        this.register({
+            name: 'get_storage_usage', category: category,
+            description: 'Mongo storage-használat tárakra bontva: a fő RAG-tárak + a helper collection-ök '
+                + '(reference/scope/ingest-run/config) aktív doc-száma (MP-1).',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok(await this.storageUsage()),
+        });
+    }
+    /** inspection → MP-1 (tables) + MP-3 (scopes) + MP-4 (scan-runs) + MP-8 (errors). */
+    registerInspection() {
+        const category = fam_mcp_interface_1.FAM_CapabilityCategory.inspection;
+        this.register({
+            name: 'list_tables', category: category,
+            description: 'A 6 fő RAG-tár felsorolása (+ a reference helper jelölése).',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok({
+                mainTables: MAIN_TABLES, helperTables: [fam_table_type_enum_1.FAM_Table.reference],
+            }),
+        });
+        this.register({
+            name: 'list_scopes', category: category,
+            description: 'A scope-entitások lapozható listája (layer/parent szűréssel).',
+            inputSchema: this.objectSchema({
+                layer: { type: 'string', description: 'Opcionális layer-szűrés.' },
+                parentScopeId: { type: 'string', description: 'Opcionális parent-szűrés.' },
+                page: { type: 'number', description: '1-alapú lapszám.' },
+                pageSize: { type: 'number', description: 'Lapméret (default 50, cap 500).' },
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                const scope_DS = new scope_reference_1.FAM_Scope_DataService({ issuer: this.issuer });
+                return this.ok(await scope_DS.listScopes({
+                    layer: this.asString(input.layer),
+                    parentScopeId: this.asString(input.parentScopeId),
+                    page: this.asNumber(input.page),
+                    pageSize: this.asNumber(input.pageSize),
+                }));
+            },
+        });
+        this.register({
+            name: 'list_scan_runs', category: category,
+            description: 'Az ingest-run-ok listája (a `FAM_IngestRun` rekordok; idővonalhoz).',
+            inputSchema: this.objectSchema({ table: this.tableSchema(false) }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                const table = this.optionalTable(input.table);
+                return this.ok(await this.listScanRuns(table));
+            },
+        });
+        this.register({
+            name: 'list_errors', category: category,
+            description: 'A persistált FAM_Error rekordok (level/source/handled szűréssel) — dsgn-008.',
+            inputSchema: this.objectSchema({
+                level: { type: 'string', description: 'Szint-szűrés (error/warning/user/...).' },
+                source: { type: 'string', description: 'Forrás-réteg szűrés (pl. FAM-EMB).' },
+                handled: { type: 'boolean', description: 'Kezelt-állapot szűrés.' },
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await errors_control_service_1.FAM_Error_ControlService.getInstance().listErrors({
+                    level: this.asString(input.level),
+                    source: this.asString(input.source),
+                    handled: typeof input.handled === 'boolean' ? input.handled : undefined,
+                }));
+            },
+        });
+        // list_kinds_tags / list_recent_writes (MP-12) — a tag/kind-aggregátum + recent-writes. A kind/tag
+        // eloszlás az adott tár (vagy minden fő tár) aktív entry-iből; a recent-writes a `__created` szerint
+        // csökkenő (legfrissebb felül) — mindkettő MP-1 entry-réteg (REUSE).
+        this.register({
+            name: 'list_kinds_tags', category: category,
+            description: 'Per-tár kind- és tag-vokabulár + eloszlás (distinct kind/tag → előfordulás-szám) az aktív '
+                + 'entry-kből.',
+            inputSchema: this.objectSchema({ table: this.tableSchema(false) }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await this.kindsAndTags(this.optionalTable(input.table)));
+            },
+        });
+        this.register({
+            name: 'list_recent_writes', category: category,
+            description: 'A legutóbbi write-ok (entry-k) `__created` szerint csökkenőben (legfrissebb felül). '
+                + 'Opcionális tár-szűrés + limit (default 20, cap 200).',
+            inputSchema: this.objectSchema({
+                table: this.tableSchema(false),
+                limit: { type: 'number', description: 'Visszaadott elemszám (default 20, cap 200).' },
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await this.recentWrites(this.optionalTable(input.table), this.asNumber(input.limit)));
+            },
+        });
+    }
+    /** maintenance → MP-2 (re-embed) + MP-3 (rebuild reference index). */
+    registerMaintenance() {
+        const category = fam_mcp_interface_1.FAM_CapabilityCategory.maintenance;
+        this.register({
+            name: 'reembed_table', category: category,
+            description: 'Egy teljes tár újra-embeddelése az aktuális modellel (modell-/provider-váltás után).',
+            inputSchema: this.objectSchema({ table: this.tableSchema(true) }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                const table = this.requireTable(input.table, 'reembed_table');
+                return this.ok(await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().reEmbedTable(table));
+            },
+        });
+        this.register({
+            name: 'reembed_scope', category: category,
+            description: 'Egy tár adott scope-ágának újra-embeddelése.',
+            inputSchema: this.objectSchema({
+                table: this.tableSchema(true), scopePath: this.scopeLayerArraySchema(),
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                const table = this.requireTable(input.table, 'reembed_scope');
+                const rawScope = this.asScopeLayers(input.scopePath);
+                const resolve = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().resolveForWrite(rawScope);
+                return this.ok(await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance()
+                    .reEmbedScope(table, resolve.scopePath));
+            },
+        });
+        this.register({
+            name: 'rebuild_reference_index', category: category,
+            description: 'A reference-index TTL-cache azonnali újraépítése (a friss reference-ek azonnal látszanak).',
+            inputSchema: this.objectSchema({}),
+            handler: async () => this.ok(await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().rebuildReferenceIndex()),
+        });
+        // repair_scope_links / deduplicate_entries (MP-12) — DRY-RUN-ONLY MVP1 (safe). A destruktív
+        // write-ág (entry-mutáció / soft-delete-összevonás) BACKLOG: vak destruktív bulk-op TILOS
+        // (dsgn-003 §4.2), ezért a `dryRun:false` kérés clear "BACKLOG" hibát ad — a `dryRun:true` (default)
+        // diagnosztikus riportot ad (mit JAVÍTANA / VONNA ÖSSZE), de NEM ír semmit.
+        this.register({
+            name: 'repair_scope_links', category: category,
+            description: 'Az entry-k scopePath-jának konzisztencia-AUDITja: feltárja a törött scope-linkeket '
+                + '(nem-létező / soft-delete-elt scopeId-ra mutató entry-ket). DRY-RUN MVP1: riportál, NEM ír. '
+                + 'A tényleges javítás (entry-mutáció) BACKLOG — `dryRun:false` → clear BACKLOG-hiba.',
+            inputSchema: this.objectSchema({
+                table: this.tableSchema(false),
+                dryRun: { type: 'boolean', description: 'MVP1: mindig true (a write-ág BACKLOG). false → BACKLOG-hiba.' },
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                this.assertDryRunOnly(input.dryRun, 'repair_scope_links', 'scope-link entry-mutáció');
+                return this.ok(await this.repairScopeLinksDryRun(this.optionalTable(input.table)));
+            },
+        });
+        this.register({
+            name: 'deduplicate_entries', category: category,
+            description: 'Duplikált entry-k AUDITja: contentHash-alapú dup-csoportok feltárása (a megtartandó + a '
+                + 'beolvasztható jelöltek). DRY-RUN MVP1: riportál, NEM ír. A tényleges összevonás (soft-delete) '
+                + 'BACKLOG — `dryRun:false` → clear BACKLOG-hiba (vak destruktív op TILOS).',
+            inputSchema: this.objectSchema({
+                table: this.tableSchema(false),
+                dryRun: { type: 'boolean', description: 'MVP1: mindig true (az összevonás BACKLOG). false → BACKLOG-hiba.' },
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                this.assertDryRunOnly(input.dryRun, 'deduplicate_entries', 'duplikátum-összevonás (soft-delete)');
+                return this.ok(await this.deduplicateEntriesDryRun(this.optionalTable(input.table)));
+            },
+        });
+    }
+    /**
+     * import / migration → MP-11 (claude-mem migráció; dsgn-009). A 4 fő művelet + a rollback wired
+     * a `FAM_ClaudeMemImport_ControlService`-re (preview → map → run/import → rollback). **Egyirányú**
+     * (dsgn-009 §7 HARD): NINCS reverse/export-capability — csak claude-mem → FAM beolvasás. Az
+     * `import_claude_mem` és a `run_import` UGYANAZ a write-művelet (alias — dsgn-009 §5.3).
+     */
+    registerImportMigration() {
+        const category = fam_mcp_interface_1.FAM_CapabilityCategory.importMigration;
+        // preview_claude_mem_import — nem-destruktív összegzés + dedup-előrejelzés (dsgn-009 §5.1).
+        this.register({
+            name: 'preview_claude_mem_import', category: category,
+            description: 'claude-mem import előnézet (nem-destruktív): counts + byType + dedup-előrejelzés + '
+                + 'projectScopes + leképezési minta. SEMMIT nem ír (dsgn-009 §5.1).',
+            inputSchema: this.importSourceSchema(),
+            handler: async (args) => this.ok(await migration_1.FAM_ClaudeMemImport_ControlService.getInstance().preview(this.toImportRequest(args))),
+        });
+        // map_claude_mem_entries — a §4 default leképezés override-ja (dsgn-009 §5.2); STILL nem ír.
+        this.register({
+            name: 'map_claude_mem_entries', category: category,
+            description: 'A claude-mem → FAM target-leképezés megjelenítése + OVERRIDE (byType/byId/scope/'
+                + 'includePrompts). A feloldott leképezési tervet adja vissza — STILL nem ír (dsgn-009 §5.2).',
+            inputSchema: this.importMapSchema(),
+            handler: async (args) => this.ok(await migration_1.FAM_ClaudeMemImport_ControlService.getInstance().map(this.toImportRequest(args))),
+        });
+        // import_claude_mem / run_import — a tényleges beírás egy batchId alatt (dsgn-009 §5.3). Alias.
+        const runHandler = async (args) => this.ok(await migration_1.FAM_ClaudeMemImport_ControlService.getInstance().run(this.toImportRequest(args)));
+        this.register({
+            name: 'import_claude_mem', category: category,
+            description: 'A claude-mem migráció tényleges beírása egy import-batch (batchId) alatt: dedup-skip + '
+                + 'map + persist + embed. Output: { ok, batchId, ingested, skipped, failed, byTable, status } (dsgn-009 §5.3).',
+            inputSchema: this.importMapSchema(), handler: runHandler,
+        });
+        this.register({
+            name: 'run_import', category: category,
+            description: 'A claude-mem import tényleges futtatása (az `import_claude_mem` aliasza, dsgn-009 §5.3).',
+            inputSchema: this.importMapSchema(), handler: runHandler,
+        });
+        // rollback_import — pontosan EGY import-batch visszavonása (soft-delete; dsgn-009 §5.4).
+        this.register({
+            name: 'rollback_import', category: category,
+            description: 'Egy korábbi import-batch visszavonása (soft-delete; pontosan az adott batchId, más '
+                + 'batch-et nem; idempotens — már visszavont → reverted:0). dsgn-009 §5.4.',
+            inputSchema: this.objectSchema({ batchId: { type: 'string', description: 'Az import-batch azonosítója.' } }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await migration_1.FAM_ClaudeMemImport_ControlService.getInstance()
+                    .rollback({ batchId: this.asString(input.batchId) ?? '' }));
+            },
+        });
+    }
+    /** debug → MP-3 (trace scope/reference). */
+    registerDebug() {
+        const category = fam_mcp_interface_1.FAM_CapabilityCategory.debug;
+        this.register({
+            name: 'trace_scope_resolution', category: category,
+            description: 'Egy scope-token write-feloldásának lépés-naplója (token→normalizált→kandidátusok→döntés).',
+            inputSchema: this.objectSchema({ scopePath: this.scopeLayerArraySchema() }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                const rawScope = this.asScopeLayers(input.scopePath);
+                return this.ok(await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance()
+                    .traceResolution(rawScope, 'write-resolve'));
+            },
+        });
+        this.register({
+            name: 'trace_reference_expansion', category: category,
+            description: 'Egy scope-filter read-expand feloldásának lépés-naplója (subtree-prefilter trace).',
+            inputSchema: this.objectSchema({ scopePath: this.scopeLayerArraySchema() }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                const rawScope = this.asScopeLayers(input.scopePath);
+                return this.ok(await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance()
+                    .traceResolution(rawScope, 'read-expand'));
+            },
+        });
+        // explain_search / inspect_chunk / inspect_embedding (MP-12) — a search-explain + chunk/embedding
+        // introspekció. Az explain_search a VALÓS retrieval-pipeline-t futtatja (MP-5) és a scoring-breakdown-t
+        // adja; az inspect_chunk/inspect_embedding az entry-t + a vektor-metát olvassa (MP-1; a nyers vektort
+        // NEM dump-olja — csak dimenzió/status/model + minta).
+        this.register({
+            name: 'explain_search', category: category,
+            description: 'Egy read-query pipeline-lépéseinek magyarázata: a VALÓS retrieval-pipeline-t futtatja '
+                + '(prefilter→vektor→weight→rank), és a per-hit scoring-breakdown-t (score/weight/finalScore) + a '
+                + 'dense-jelzőket + uncertaintyNotes-t adja vissza (NEM néma, NEM ír).',
+            inputSchema: this.objectSchema({
+                tables: {
+                    type: 'array', items: { type: 'string', enum: Object.values(fam_table_type_enum_1.FAM_Table) },
+                    description: '1+ fő tár (a `reference` tilos — helper).',
+                },
+                query: { type: 'string', description: 'A keresési phrase.' },
+                topK: { type: 'number', description: 'Találat-limit (config-default 5).' },
+                minScore: { type: 'number', description: 'Minimum finalScore-küszöb.' },
+                scopeFilter: this.scopeLayerArraySchema(),
+                tagFilter: { type: 'array', items: { type: 'string' }, description: 'Tag-szűrő (OR).' },
+                kindFilter: { type: 'string', description: 'Egyetlen kind-szűrő.' },
+            }),
+            handler: async (args) => this.ok(await this.explainSearch(this.asObject(args))),
+        });
+        this.register({
+            name: 'inspect_chunk', category: category,
+            description: 'Egy chunk (entry) teljes mező-introspekciója (content/kind/tags/scopePath/source/position/'
+                + 'chunk-meta + embedding-státusz). A `table` szűkíti a keresést (vagy minden fő tár).',
+            inputSchema: this.objectSchema({
+                id: { type: 'string', description: 'Az entry _id-ja.' },
+                table: this.tableSchema(false),
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await this.inspectChunk(this.asString(input.id), this.optionalTable(input.table)));
+            },
+        });
+        this.register({
+            name: 'inspect_embedding', category: category,
+            description: 'Egy entry embedding-vektorának introspekciója: dimenzió / embeddingStatus / embeddingModel '
+                + '+ egy rövid előnézet-minta (a nyers teljes vektort NEM dump-olja — context-tisztaság).',
+            inputSchema: this.objectSchema({
+                id: { type: 'string', description: 'Az entry _id-ja.' },
+                table: this.tableSchema(false),
+            }),
+            handler: async (args) => {
+                const input = this.asObject(args);
+                return this.ok(await this.inspectEmbedding(this.asString(input.id), this.optionalTable(input.table)));
+            },
+        });
+    }
+    // =========================================================================
+    // Wired handler-helpers (delegálás az engine-ekre)
+    // =========================================================================
+    /** Per-tár statisztika (aktív elem-szám + embedding-státusz bontás) — MP-1. */
+    async tableStats(table) {
+        const tables = table ? [table] : MAIN_TABLES;
+        const result = [];
+        for (const target of tables) {
+            const registryEntry = embedding_1.FAM_STORE_REGISTRY.find((entry) => entry.table === target);
+            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 };
+            for (const entry of entries) {
+                const status = entry.embeddingStatus ?? 'pending';
+                byStatus[status] = (byStatus[status] ?? 0) + 1;
+            }
+            result.push({ table: target, count: entries.length, embeddingStatus: byStatus });
+        }
+        return table ? result[0] ?? { table: table, count: 0 } : result;
+    }
+    /** Az ingest-run-ok listája (a `FAM_IngestRun` rekordok) — MP-4. */
+    async listScanRuns(table) {
+        const runDataService = new ingest_1.FAM_IngestRun_DataService({ issuer: this.issuer });
+        const runs = await runDataService.listRuns();
+        return table ? runs.filter((run) => this.runHasTable(run.table, table)) : runs;
+    }
+    /** Egy run érinti-e az adott tárat (a `table` mező lehet egyetlen tár vagy tömb). */
+    runHasTable(runTable, table) {
+        if (!runTable) {
+            return false;
+        }
+        return Array.isArray(runTable) ? runTable.includes(table) : runTable === table;
+    }
+    // =========================================================================
+    // MP-12 config-diagnostics: env / Mongo / vector (a `fam doctor` invokálja)
+    // =========================================================================
+    /**
+     * `validate_environment` (MP-12, dsgn-012 §7.1) — a `process.env` infra-szintű változóinak
+     * jelenlét-ellenőrzése provider-feltételes kötelezőséggel. NEM olvas DB-t, NEM dob (a hiányt
+     * az `ok:false` + a `missing[]` jelzi — deskriptív, nem néma). A titok-értékeket NEM logolja
+     * (csak a jelenlét-tényt). A `doctor` env-checkje ezt invokálja.
+     */
+    validateEnvironment() {
+        const provider = (process.env.EMBEDDING_PROVIDER || 'openai').trim();
+        const present = [];
+        const missing = [];
+        // Kötelező infra-változók (dsgn-012 §7.1): MONGODB_URI + a provider-választás.
+        this.checkEnv('MONGODB_URI', 'A saját MongoDB connection string (NEM Atlas), pl. mongodb://127.0.0.1:27017.', present, missing);
+        this.checkEnv('EMBEDDING_PROVIDER', "Az aktív embedding-provider: 'openai' | 'lmstudio'.", present, missing, true);
+        // Provider-feltételes kötelezőség.
+        if (provider === 'openai') {
+            this.checkEnv('OPENAI_API_KEY', 'OpenAI provider esetén kötelező az API-kulcs.', present, missing);
+        }
+        else if (provider === 'lmstudio') {
+            this.checkEnv('LMSTUDIO_BASE_URL', 'LM Studio provider esetén kötelező a lokális OpenAI-kompatibilis endpoint.', present, missing);
+            this.checkEnv('LMSTUDIO_EMBEDDING_MODEL', 'LM Studio provider esetén kötelező a betöltött embedding-modell neve.', present, missing);
+        }
+        return { ok: missing.length === 0, provider: provider, present: present, missing: missing };
+    }
+    /** Egy env-változó jelenlét-ellenőrzése (`treatDefaultAsPresent`: van builtin default, ezért sosem hiányzik). */
+    checkEnv(name, hint, present, missing, treatDefaultAsPresent = false) {
+        const value = process.env[name];
+        if ((value && value.trim().length) || treatDefaultAsPresent) {
+            present.push(name);
+            return;
+        }
+        missing.push({ name: name, hint: hint });
+    }
+    /**
+     * `test_mongodb_connection` (MP-12) — egy könnyű olvasás a `fam_config` collection-ön (a Dynamo
+     * DataService a global service-collection-ön át pingel). Siker → `{ ok:true, reachable:true }`;
+     * connect-hiba → `FAM-DB-CONNECT-001` (a `doctor` mongodb-checkje így FAIL-t kap, nem néma).
+     */
+    async testMongoConnection() {
+        try {
+            const dataService = new config_data_service_1.FAM_Config_DataService({ issuer: this.issuer });
+            // A lekérdezés ténye a ping (a tartalom nem érdekes); üres collection is OK (reachable).
+            await dataService.findActiveList({});
+            return { ok: true, reachable: true };
+        }
+        catch (error) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.dbConnect,
+                message: 'A MongoDB-kapcsolat próbája sikertelen — a `fam_config` collection nem olvasható. '
+                    + 'Ellenőrizd, hogy fut-e a Mongo, és helyes-e a MONGODB_URI (NEM Atlas; lokális/saját).',
+                issuer: this.issuer,
+                cause: error,
+                context: { operation: 'test-mongodb-connection' },
+            });
+        }
+    }
+    /**
+     * `test_vector_search` (MP-12, dsgn-006 §4) — LVS smoke: egy próba-szöveg embed-elése + koszinusz-
+     * keresés a tár(ak) pool-jában. Per-tár visszaadja a pool-méretet + a próba-keresés státuszát
+     * (`searched`/`empty-pool`/`embedding-unavailable`). Üres pool / embedding-hiány → NEM dob (a
+     * `doctor` ezt a bootstrap-skip állapotot jelzi), de a struktúra deskriptív (no-silent-failure).
+     */
+    async testVectorSearch(table) {
+        const probe = 'fdp agent memory vector search probe';
+        const tables = table ? [table] : MAIN_TABLES;
+        const vectorSearch = embedding_1.FAM_VectorSearch_ControlService.getInstance();
+        // A query-vektort EGYSZER embeddeljük (graceful: embedding-hiány → string-only smoke).
+        let queryVector = [];
+        let embeddingAvailable = false;
+        try {
+            queryVector = await embedding_1.FAM_Embedding_ControlService.getInstance()
+                .embedOne({ text: probe, callType: 'embed-query', issuer: this.issuer });
+            embeddingAvailable = queryVector.length > 0;
+        }
+        catch {
+            embeddingAvailable = false;
+        }
+        const results = [];
+        for (const target of tables) {
+            const poolSize = vectorSearch.getPoolSize(target);
+            const hydrated = vectorSearch.isHydrated(target);
+            let topHitScore = null;
+            let status;
+            if (!embeddingAvailable) {
+                status = 'embedding-unavailable';
+            }
+            else if (!poolSize) {
+                status = 'empty-pool';
+            }
+            else {
+                try {
+                    const hits = await vectorSearch.search({ table: target, queryVector: queryVector, topK: 1 });
+                    topHitScore = hits.length ? hits[0].score : null;
+                    status = 'searched';
+                }
+                catch {
+                    status = 'empty-pool';
+                }
+            }
+            results.push({ table: target, poolSize: poolSize, hydrated: hydrated, topHitScore: topHitScore, status: status });
+        }
+        return { probe: probe, embeddingAvailable: embeddingAvailable, tables: results };
+    }
+    // =========================================================================
+    // MP-12 high-level-stats: layer-stats / storage-usage
+    // =========================================================================
+    /** `get_layer_stats` (MP-12) — a scope-fa layerenkénti aggregátuma (scope-szám + root/child bontás). */
+    async layerStats() {
+        const scope_DS = new scope_reference_1.FAM_Scope_DataService({ issuer: this.issuer });
+        const all = await scope_DS.findAllActive();
+        const byLayer = new Map();
+        for (const scope of all) {
+            const layer = scope.layer ?? '(unknown)';
+            const bucket = byLayer.get(layer) ?? { scopeCount: 0, rootCount: 0, childCount: 0 };
+            bucket.scopeCount++;
+            if (scope.parentScopeId) {
+                bucket.childCount++;
+            }
+            else {
+                bucket.rootCount++;
+            }
+            byLayer.set(layer, bucket);
+        }
+        return Array.from(byLayer.entries()).map(([layer, bucket]) => ({ layer: layer, ...bucket }));
+    }
+    /**
+     * `get_storage_usage` (MP-12) — a fő RAG-tárak + a helper collection-ök aktív doc-száma. A Dynamo
+     * base-nek nincs natív `count`, ezért aktív-elemszám (`findDataList(...).length`) — collection-méret-becslés.
+     */
+    async storageUsage() {
+        const collections = [];
+        // Fő RAG-tárak (a store-registry-n át, a per-tár dataParams-szal).
+        for (const registryEntry of embedding_1.FAM_STORE_REGISTRY) {
+            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+            const entries = await dataService.findHydratableList({});
+            collections.push({ collection: `fam_${registryEntry.table}`, activeDocs: entries.length });
+        }
+        // Helper collection-ök (reference / scope / ingest-run / config).
+        const reference_DS = new scope_reference_1.FAM_Reference_DataService({ issuer: this.issuer });
+        collections.push({ collection: 'fam_reference', activeDocs: (await reference_DS.findActive()).length });
+        const scope_DS = new scope_reference_1.FAM_Scope_DataService({ issuer: this.issuer });
+        collections.push({ collection: 'fam_scopes', activeDocs: (await scope_DS.findAllActive()).length });
+        const run_DS = new ingest_1.FAM_IngestRun_DataService({ issuer: this.issuer });
+        collections.push({ collection: 'fam_ingest_runs', activeDocs: (await run_DS.listRuns()).length });
+        const config_DS = new config_data_service_1.FAM_Config_DataService({ issuer: this.issuer });
+        collections.push({ collection: 'fam_config', activeDocs: (await config_DS.findActiveList({})).length });
+        const totalActiveDocs = collections.reduce((sum, entry) => sum + entry.activeDocs, 0);
+        return { collections: collections, totalActiveDocs: totalActiveDocs };
+    }
+    // =========================================================================
+    // MP-12 inspection: kinds/tags / recent-writes
+    // =========================================================================
+    /** `list_kinds_tags` (MP-12) — per-tár distinct kind/tag eloszlás (előfordulás-szám) az aktív entry-kből. */
+    async kindsAndTags(table) {
+        const tables = table ? [table] : MAIN_TABLES;
+        const result = [];
+        for (const target of tables) {
+            const entries = await this.loadTableEntries(target);
+            const kindCounts = new Map();
+            const tagCounts = new Map();
+            for (const entry of entries) {
+                if (entry.kind) {
+                    kindCounts.set(entry.kind, (kindCounts.get(entry.kind) ?? 0) + 1);
+                }
+                for (const tag of entry.tags ?? []) {
+                    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+                }
+            }
+            result.push({
+                table: target,
+                kinds: this.sortedCounts(kindCounts).map((entry) => ({ kind: entry.label, count: entry.count })),
+                tags: this.sortedCounts(tagCounts).map((entry) => ({ tag: entry.label, count: entry.count })),
+            });
+        }
+        return result;
+    }
+    /** `list_recent_writes` (MP-12) — a legutóbbi entry-k `__created` szerint csökkenőben (legfrissebb felül). */
+    async recentWrites(table, limit) {
+        const cappedLimit = Math.min(Math.max(limit ?? 20, 1), 200);
+        const tables = table ? [table] : MAIN_TABLES;
+        const collected = [];
+        for (const target of tables) {
+            const entries = await this.loadTableEntries(target);
+            for (const entry of entries) {
+                if (!entry._id) {
+                    continue;
+                }
+                const created = entry.__created;
+                collected.push({
+                    id: entry._id,
+                    table: target,
+                    kind: entry.kind,
+                    tags: entry.tags ?? [],
+                    createdMs: created ? new Date(created).getTime() : 0,
+                    contentPreview: this.preview(entry.content),
+                });
+            }
+        }
+        collected.sort((a, b) => b.createdMs - a.createdMs);
+        return collected.slice(0, cappedLimit);
+    }
+    // =========================================================================
+    // MP-12 maintenance: repair-scope-links / deduplicate-entries — DRY-RUN-ONLY
+    // =========================================================================
+    /**
+     * A maintenance-eszközök destruktív-ág kapuja: MVP1-ben CSAK dry-run (`dryRun` undefined/true). A
+     * `dryRun:false` clear BACKLOG-hibát ad — a vak destruktív bulk-op TILOS (dsgn-003 §4.2), a tényleges
+     * írás-ág későbbi fázis (külön maintenance-engine + per-entitás megerősítés).
+     */
+    assertDryRunOnly(dryRun, capability, destructiveOp) {
+        if (dryRun === false) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                message: `A(z) '${capability}' destruktív ága (${destructiveOp}) BACKLOG — MVP1-ben CSAK dry-run `
+                    + '(diagnosztikus riport, NEM ír). Vak destruktív bulk-op nem engedélyezett. Hívd `dryRun:true`-val '
+                    + '(default) a riportért; a tényleges karbantartás későbbi fázis.',
+                issuer: this.issuer,
+                context: { operation: `capability-invoke:${capability}` },
+            });
+        }
+    }
+    /**
+     * `repair_scope_links` DRY-RUN (MVP1) — feltárja a törött scope-linkeket: az aktív entry-k, amelyek
+     * `scopePath`-ja olyan `scopeId`-ra mutat, ami már NEM aktív a scope-fán. NEM ír — csak riportál
+     * (mit JAVÍTANA). A tényleges javítás BACKLOG.
+     */
+    async repairScopeLinksDryRun(table) {
+        const scope_DS = new scope_reference_1.FAM_Scope_DataService({ issuer: this.issuer });
+        const activeScopeIds = new Set((await scope_DS.findAllActive()).map((scope) => scope._id ?? ''));
+        const tables = table ? [table] : MAIN_TABLES;
+        let scannedEntries = 0;
+        const brokenLinks = [];
+        for (const target of tables) {
+            const entries = await this.loadTableEntries(target);
+            for (const entry of entries) {
+                scannedEntries++;
+                const refs = (entry.scopePath ?? []);
+                const missing = refs
+                    .map((ref) => ref.scopeId)
+                    .filter((scopeId) => scopeId && !activeScopeIds.has(scopeId));
+                if (missing.length && entry._id) {
+                    brokenLinks.push({ id: entry._id, table: target, missingScopeIds: missing });
+                }
+            }
+        }
+        return { dryRun: true, scannedEntries: scannedEntries, brokenLinks: brokenLinks };
+    }
+    /**
+     * `deduplicate_entries` DRY-RUN (MVP1) — feltárja a `contentHash`-azonos dup-csoportokat: a megtartandó
+     * (legrégebbi `__created`) + a beolvasztható jelöltek. NEM ír — csak riportál (mit VONNA ÖSSZE). A
+     * tényleges összevonás (soft-delete) BACKLOG.
+     */
+    async deduplicateEntriesDryRun(table) {
+        const tables = table ? [table] : MAIN_TABLES;
+        let scannedEntries = 0;
+        const duplicateGroups = [];
+        for (const target of tables) {
+            const entries = await this.loadTableEntries(target);
+            const byHash = new Map();
+            for (const entry of entries) {
+                scannedEntries++;
+                if (!entry.contentHash || !entry._id) {
+                    continue;
+                }
+                const bucket = byHash.get(entry.contentHash) ?? [];
+                bucket.push(entry);
+                byHash.set(entry.contentHash, bucket);
+            }
+            for (const [contentHash, group] of byHash.entries()) {
+                if (group.length < 2) {
+                    continue;
+                }
+                // A megtartandó = a legrégebbi (`__created` ASC); a többi a merge-jelölt.
+                const sorted = group.slice().sort((a, b) => this.createdMs(a) - this.createdMs(b));
+                const keepId = sorted[0]._id ?? '';
+                const mergeIds = sorted.slice(1).map((entry) => entry._id ?? '').filter((id) => id.length > 0);
+                duplicateGroups.push({ table: target, contentHash: contentHash, keepId: keepId, mergeIds: mergeIds });
+            }
+        }
+        return { dryRun: true, scannedEntries: scannedEntries, duplicateGroups: duplicateGroups };
+    }
+    // =========================================================================
+    // MP-12 debug: explain-search / inspect-chunk / inspect-embedding
+    // =========================================================================
+    /**
+     * `explain_search` (MP-12, dsgn-005) — a VALÓS retrieval-pipeline-t futtatja egyetlen query-re, és a
+     * per-hit scoring-breakdown-t (score/weight/finalScore) + a dense-jelzőket + uncertaintyNotes-t adja.
+     * NEM ír. A `tables` kötelező + a `reference` tilos (helper) — defense-in-depth kihagyás.
+     */
+    async explainSearch(input) {
+        const tables = this.asTableArray(input.tables).filter((target) => target !== fam_table_type_enum_1.FAM_Table.reference);
+        const query = this.asString(input.query);
+        if (!tables.length || !query) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                message: "Az 'explain_search'-hez kötelező a `tables` (1+ fő tár, a `reference` tilos) + a `query`.",
+                issuer: this.issuer,
+                context: { operation: 'capability-invoke:explain_search' },
+            });
+        }
+        const request = {
+            queries: [{
+                    tables: tables,
+                    query: query,
+                    topK: this.asNumber(input.topK),
+                    minScore: this.asNumber(input.minScore),
+                    scopeFilter: this.asScopeLayers(input.scopeFilter),
+                    tagFilter: this.asStringArray(input.tagFilter),
+                    kindFilter: this.asString(input.kindFilter),
+                }],
+            includeContent: false,
+        };
+        const response = await retrieval_1.FAM_Retrieval_ControlService.getInstance().read(request);
+        const result = response.results[0];
+        return {
+            query: result?.query ?? query,
+            tables: result?.tables ?? tables,
+            scoring: (result?.hits ?? []).map((hit) => ({
+                id: hit.id, table: hit.table, score: hit.score, weight: hit.weight, finalScore: hit.finalScore,
+                kind: hit.kind, tags: hit.tags,
+            })),
+            denseResults: result?.denseResults ?? false,
+            totalRelevant: result?.totalRelevant ?? 0,
+            truncated: result?.truncated ?? false,
+            suggestions: result?.suggestions ?? [],
+            uncertaintyNotes: result?.uncertaintyNotes ?? [],
+        };
+    }
+    /** `inspect_chunk` (MP-12) — egy entry teljes mező-introspekciója (a megadott `id`-re; opc. tár-szűkítés). */
+    async inspectChunk(id, table) {
+        const entry = await this.requireEntryById(id, table, 'inspect_chunk');
+        return {
+            id: entry._id,
+            table: entry.table,
+            kind: entry.kind,
+            tags: entry.tags ?? [],
+            content: entry.content,
+            contentHash: entry.contentHash,
+            scopePath: (entry.scopePath ?? []),
+            referenceLinks: entry.referenceLinks ?? [],
+            weight: entry.weight,
+            importance: entry.importance,
+            source: entry.source,
+            sourceFilePath: entry.sourceFilePath ?? null,
+            chunkIndex: entry.chunkIndex,
+            chunkTotal: entry.chunkTotal,
+            chunkType: entry.chunkType,
+            position: entry.position,
+            headingPath: entry.headingPath ?? [],
+            embeddingStatus: entry.embeddingStatus ?? 'pending',
+            embeddingModel: entry.embeddingModel,
+            createdMs: this.createdMs(entry),
+            lastModifiedMs: entry.__lastModified ? new Date(entry.__lastModified).getTime() : 0,
+        };
+    }
+    /**
+     * `inspect_embedding` (MP-12) — egy entry embedding-vektor-metája: dimenzió / status / model + egy
+     * rövid előnézet-minta (az első néhány komponens). A nyers TELJES vektort NEM dump-olja (context-tisztaság).
+     */
+    async inspectEmbedding(id, table) {
+        const entry = await this.requireEntryById(id, table, 'inspect_embedding');
+        const vector = entry.contentVector ?? [];
+        return {
+            id: entry._id,
+            table: entry.table,
+            embeddingStatus: entry.embeddingStatus ?? 'pending',
+            embeddingModel: entry.embeddingModel ?? null,
+            dimensions: vector.length,
+            hasVector: vector.length > 0,
+            samplePreview: vector.slice(0, 8),
+        };
+    }
+    // =========================================================================
+    // MP-12 közös entry-helperek (lazy DataService — eager-resolve elkerülés)
+    // =========================================================================
+    /** Egy fő tár aktív entry-i (a per-tár dataParams-szal). Nem-fő/ismeretlen tár → üres. */
+    async loadTableEntries(table) {
+        const registryEntry = embedding_1.FAM_STORE_REGISTRY.find((entry) => entry.table === table);
+        if (!registryEntry) {
+            return [];
+        }
+        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        return dataService.findHydratableList({});
+    }
+    /** Egy entry feloldása `id`-ből (a megadott tárból, vagy minden fő tárból). Nincs → `FAM-MCP-DISPATCH-002`. */
+    async requireEntryById(id, table, capability) {
+        if (!id) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                message: `A(z) '${capability}' capability-hez kötelező az 'id' (az entry _id-ja).`,
+                issuer: this.issuer,
+                context: { operation: `capability-invoke:${capability}` },
+            });
+        }
+        const tables = table ? [table] : MAIN_TABLES;
+        for (const target of tables) {
+            const registryEntry = embedding_1.FAM_STORE_REGISTRY.find((entry) => entry.table === target);
+            if (!registryEntry) {
+                continue;
+            }
+            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+            const entry = await dataService.findData({ _id: id }, true);
+            if (entry && entry._id) {
+                return entry;
+            }
+        }
+        throw fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+            message: `A(z) '${capability}' nem talált entry-t a(z) '${id}' _id-ra `
+                + `${table ? `a(z) '${table}' tárban` : 'egyetlen fő tárban sem'}.`,
+            issuer: this.issuer,
+            context: { operation: `capability-invoke:${capability}` },
+        });
+    }
+    /** Egy entry `__created` epoch-ms-e (vagy 0). */
+    createdMs(entry) {
+        return entry.__created ? new Date(entry.__created).getTime() : 0;
+    }
+    /** Egy content rövid előnézete (max 160 karakter, sortörés-normalizálva). */
+    preview(content) {
+        if (!content) {
+            return '';
+        }
+        const normalized = content.replace(/\s+/g, ' ').trim();
+        return normalized.length > 160 ? `${normalized.slice(0, 160)}…` : normalized;
+    }
+    /** Egy count-map → rendezett `{ label, count }[]` (count DESC, majd label ASC). */
+    sortedCounts(counts) {
+        return Array.from(counts.entries())
+            .map(([label, count]) => ({ label: label, count: count }))
+            .sort((a, b) => (b.count - a.count) || (a.label < b.label ? -1 : 1));
+    }
+    /** Egy érték `FAM_Table[]`-ként (a fő + helper tárakból; ismeretlen érték kihagyva). */
+    asTableArray(value) {
+        if (!Array.isArray(value)) {
+            return [];
+        }
+        const tables = [];
+        for (const item of value) {
+            const table = this.optionalTable(item);
+            if (table) {
+                tables.push(table);
+            }
+        }
+        return tables;
+    }
+    /** Egy érték `string[]`-ként (a nem-string elemeket kihagyva; üres → undefined). */
+    asStringArray(value) {
+        if (!Array.isArray(value)) {
+            return undefined;
+        }
+        const result = value.filter((item) => typeof item === 'string' && item.length > 0);
+        return result.length ? result : undefined;
+    }
+    // =========================================================================
+    // registry-építés + sablon-helperek
+    // =========================================================================
+    /** Egy wired capability regisztrálása. */
+    register(descriptor) {
+        this.registry.set(descriptor.name, descriptor);
+    }
+    // (Eltávolítva: `registerLateBound` — FAM-REV-022. MVP1-ben MINDEN capability valós handlerrel
+    //  regisztrált [`register`]; nincs "pending MP-X" late-bind stub. A descriptor `lateBound`/`pendingMp`
+    //  mezője megmarad [defenzív, a `list`/`describe` riport olvassa], de jelenleg egyik capability sem
+    //  állítja `true`-ra.)
+    /** Egy `object` JSON-schema a megadott property-kből. */
+    objectSchema(properties) {
+        return { type: 'object', properties: properties, additionalProperties: false };
+    }
+    /** A `table` property-schema (a fő tárak enuma; required jelzéssel). */
+    tableSchema(required) {
+        const schema = {
+            type: 'string',
+            enum: Object.values(fam_table_type_enum_1.FAM_Table),
+            description: required ? 'A cél-tár (kötelező).' : 'Opcionális tár-szűrés (üres → minden fő tár).',
+        };
+        return schema;
+    }
+    /** A `scopePath` array-schema (raw layer-lánc). */
+    scopeLayerArraySchema() {
+        return {
+            type: 'array',
+            description: 'Nyers scope-lánc (root→leaf): [{ layer, rawName }] párok.',
+            items: this.objectSchema({
+                layer: { type: 'string', description: 'A dinamikus layer-név (pl. organization/project).' },
+                rawName: { type: 'string', description: 'A nyers (feloldatlan) scope-név.' },
+            }),
+        };
+    }
+    // =========================================================================
+    // import / migration schema + arg-coerce (MP-11, dsgn-009)
+    // =========================================================================
+    /** A claude-mem import forrás-schema (preview/source-readers): from + path + includePrompts. */
+    importSourceSchema() {
+        return this.objectSchema({
+            from: {
+                type: 'string', enum: Object.values(migration_1.FAM_ClaudeMemSource_Type),
+                description: 'A claude-mem forrás-csatorna (default `export-json`, függőség-mentes).',
+            },
+            path: { type: 'string', description: 'export-JSON/SQLite útvonal VAGY worker base-URL.' },
+            includePrompts: { type: 'boolean', description: 'A user_prompt-ok be-importálása (default false).' },
+        });
+    }
+    /** A map/run import-schema: a forrás-schema + az `overrides` blokk (byType/byId/scope/includePrompts). */
+    importMapSchema() {
+        const schema = this.importSourceSchema();
+        if (schema.properties) {
+            schema.properties.overrides = {
+                type: 'object',
+                description: 'A §4 default leképezés felülírása (byType / byId / scope / includePrompts).',
+                additionalProperties: true,
+            };
+        }
+        return schema;
+    }
+    /** A nyers args → `FAM_ImportRequest` (source default `claude-mem`; from default `export-json`). */
+    toImportRequest(args) {
+        const input = this.asObject(args);
+        return {
+            source: this.asString(input.source) ?? 'claude-mem',
+            from: this.asImportFrom(input.from),
+            path: this.asString(input.path),
+            includePrompts: typeof input.includePrompts === 'boolean' ? input.includePrompts : undefined,
+            overrides: this.asImportOverrides(input.overrides),
+        };
+    }
+    /** Egy érték `FAM_ClaudeMemSource_Type`-ként (vagy undefined → a engine default-ol export-json-ra). */
+    asImportFrom(value) {
+        const from = this.asString(value);
+        return from
+            ? Object.values(migration_1.FAM_ClaudeMemSource_Type).find((source) => source === from)
+            : undefined;
+    }
+    /** A nyers `overrides` → `FAM_ImportOverrides` (byType/byId target-override + scope + includePrompts). */
+    asImportOverrides(value) {
+        if (!value || typeof value !== 'object') {
+            return undefined;
+        }
+        const raw = value;
+        const overrides = {};
+        const byType = this.asTargetOverrideMap(raw.byType);
+        if (Object.keys(byType).length) {
+            overrides.byType = byType;
+        }
+        const byId = this.asTargetOverrideMap(raw.byId);
+        if (Object.keys(byId).length) {
+            overrides.byId = byId;
+        }
+        const scope = this.asScopeOverrideMap(raw.scope);
+        if (Object.keys(scope).length) {
+            overrides.scope = scope;
+        }
+        if (typeof raw.includePrompts === 'boolean') {
+            overrides.includePrompts = raw.includePrompts;
+        }
+        return Object.keys(overrides).length ? overrides : undefined;
+    }
+    /** Egy nyers map → `{ key: { table?, kind?, tags? } }` target-override map. */
+    asTargetOverrideMap(value) {
+        const result = {};
+        if (!value || typeof value !== 'object') {
+            return result;
+        }
+        for (const [key, raw] of Object.entries(value)) {
+            const entry = this.asObject(raw);
+            const override = {};
+            const table = this.optionalTable(entry.table);
+            if (table) {
+                override.table = table;
+            }
+            if (typeof entry.kind === 'string') {
+                override.kind = entry.kind;
+            }
+            if (Array.isArray(entry.tags)) {
+                override.tags = entry.tags.filter((tag) => typeof tag === 'string');
+            }
+            if (Object.keys(override).length) {
+                result[key] = override;
+            }
+        }
+        return result;
+    }
+    /** Egy nyers scope-override map → `{ 'project:<name>': { scopePath: [{layer,rawName}] } }`. */
+    asScopeOverrideMap(value) {
+        const result = {};
+        if (!value || typeof value !== 'object') {
+            return result;
+        }
+        for (const [key, raw] of Object.entries(value)) {
+            const entry = this.asObject(raw);
+            const layers = this.asScopeLayers(entry.scopePath);
+            if (layers.length) {
+                result[key] = { scopePath: layers.map((layer) => ({ layer: layer.layer, rawName: layer.rawName })) };
+            }
+        }
+        return result;
+    }
+    /** A `ok` outcome (a wired handlerek strukturált eredménye). */
+    ok(data) {
+        return { data: data };
+    }
+    // =========================================================================
+    // argumentum-coerce helperek (a nyers JSON args típus-szűrése)
+    // =========================================================================
+    /** A nyers args → kulcs→érték objektum (nem-objektum → üres). */
+    asObject(args) {
+        return args && typeof args === 'object' ? args : {};
+    }
+    /** Egy érték string-ként (vagy undefined). */
+    asString(value) {
+        return typeof value === 'string' && value.length ? value : undefined;
+    }
+    /** Egy érték number-ként (vagy undefined). */
+    asNumber(value) {
+        return typeof value === 'number' ? value : undefined;
+    }
+    /** Egy érték opcionális `FAM_Table`-ként (a fő tárak közül; egyébként undefined). */
+    optionalTable(value) {
+        const tableValue = this.asString(value);
+        return tableValue ? Object.values(fam_table_type_enum_1.FAM_Table).find((table) => table === tableValue) : undefined;
+    }
+    /** Egy kötelező `FAM_Table` (hiányzó/ismeretlen → `FAM-CAP` hiba). */
+    requireTable(value, capability) {
+        const table = this.optionalTable(value);
+        if (!table) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                message: `A(z) '${capability}' capability-hez kötelező a 'table' (a 6 fő tár egyike).`,
+                issuer: this.issuer,
+                context: { operation: `capability-invoke:${capability}` },
+            });
+        }
+        return table;
+    }
+    /** Egy érték nyers scope-lánc-ként (`{ layer, rawName }[]`; nem-tömb → üres). */
+    asScopeLayers(value) {
+        if (!Array.isArray(value)) {
+            return [];
+        }
+        const layers = [];
+        for (const item of value) {
+            const obj = this.asObject(item);
+            const layer = this.asString(obj.layer);
+            const rawName = this.asString(obj.rawName);
+            if (layer && rawName) {
+                layers.push({ layer: layer, rawName: rawName });
+            }
+        }
+        return layers;
+    }
+    /** A config-context feloldása az args-ból (table + opc. scopePath canonical-resolve). */
+    async toConfigContext(input) {
+        const table = this.optionalTable(input.table);
+        const rawScope = this.asScopeLayers(input.scopePath);
+        if (!rawScope.length) {
+            return { table: table };
+        }
+        const expand = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().resolveForWrite(rawScope);
+        return { table: table, scopePath: expand.scopePath };
+    }
+}
+exports.FAM_CapabilityRegistry = FAM_CapabilityRegistry;