@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/migration/_services/fam-claude-mem-import.control-service.js

@@ -0,0 +1,533 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ClaudeMemImport_ControlService = void 0;
+const tslib_1 = require("tslib");
+const crypto = tslib_1.__importStar(require("crypto"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const errors_control_service_1 = require("../../../_routes/server/errors/errors.control-service");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_entry_data_model_1 = require("../../../_models/data-models/fam-entry.data-model");
+const embedding_1 = require("../../embedding");
+const scope_reference_1 = require("../../scope-reference");
+const fam_claude_mem_source_type_enum_1 = require("../_enums/fam-claude-mem-source.type-enum");
+const fam_import_content_hash_util_1 = require("../_collections/fam-import-content-hash.util");
+const fam_target_mapping_util_1 = require("../_collections/fam-target-mapping.util");
+const fam_claude_mem_export_reader_service_1 = require("./fam-claude-mem-export-reader.service");
+const fam_claude_mem_sqlite_reader_service_1 = require("./fam-claude-mem-sqlite-reader.service");
+const fam_claude_mem_worker_reader_service_1 = require("./fam-claude-mem-worker-reader.service");
+const fam_import_dedup_data_service_1 = require("./fam-import-dedup.data-service");
+/** A preview `mappingPreview` mintájának mérete (nem a teljes lista — a `map` adja a teljeset). */
+const PREVIEW_SAMPLE_SIZE = 10;
+/** A claude-mem `project` raw név alapértelmezett scope-layer-e (dsgn-009 §4 — project-layer). */
+const PROJECT_SCOPE_LAYER = 'project';
+/**
+ * `FAM_ClaudeMemImport_ControlService` (MP-11, dsgn-009) — a claude-mem → FAM **egyirányú** migrációs
+ * engine. Singleton. A négy-lépéses, nem-destruktív folyamatot (preview → map → run → rollback)
+ * implementálja, a SP-11.1 reader-ekre (export-JSON / SQLite / worker-api) + a SP-11.2 dedup +
+ * target-mapping-re + a MP-2 embedding-re + a MP-3 scope-resolve-ra építve.
+ *
+ * **Egyirányúság (HARD, dsgn-009 §7):** SOHA nincs FDP→claude-mem export/reverse — ez az engine csak
+ * BEOLVAS és FAM-be ír; az `importSource`/`importSourceId` provenance (audit/dedup), nem
+ * vissza-szinkron.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** NEM tartunk élő DataService mezőt — minden
+ * DB-művelet előtt lazy `new FAM_Entry_DataService`.
+ */
+class FAM_ClaudeMemImport_ControlService {
+    static _instance;
+    /** Default issuer (a migrációs hibák issuer-éhez; dsgn-008). */
+    issuer = 'FAM_ClaudeMemImport_ControlService';
+    static getInstance() {
+        if (!FAM_ClaudeMemImport_ControlService._instance) {
+            FAM_ClaudeMemImport_ControlService._instance = new FAM_ClaudeMemImport_ControlService();
+        }
+        return FAM_ClaudeMemImport_ControlService._instance;
+    }
+    // =========================================================================
+    // (1) PREVIEW — nem-destruktív (dsgn-009 §5.1)
+    // =========================================================================
+    /**
+     * `preview` (dsgn-009 §5.1) — SEMMIT nem ír. Beolvassa a forrást, megadja a counts / byType
+     * bontást, a dedup-előrejelzést (a SP-11.2 dedup-lépcsőit write nélkül futtatva), a projekt-scope
+     * feloldásokat (confidence-szel) és egy leképezési mintát. A scope-feloldás itt is a MP-3-on megy,
+     * de SOHA nem hoz létre scope-ot (preview = read-only — az auto-create-et kihagyjuk).
+     */
+    async preview(request) {
+        const data = await this.readSource(request);
+        const includePrompts = this.resolveIncludePrompts(request);
+        const warnings = [...data.warnings];
+        // byType (observation type-eloszlás).
+        const byType = {};
+        for (const record of data.records) {
+            if (record.type) {
+                byType[record.type] = (byType[record.type] ?? 0) + 1;
+            }
+        }
+        // dedup-előrejelzés (write nélkül) + a leképezési minta összeállítása.
+        const dedup = { willImport: 0, willSkipExisting: 0, willSkipDuplicateContent: 0 };
+        const mappingPreview = [];
+        const previewUncertainty = [];
+        for (const record of data.records) {
+            const plan = await this.buildPlan({ record: record, request: request, allowCreateScope: false, uncertainty: previewUncertainty });
+            const verdict = await fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.getInstance().verdictFor({
+                record: record, table: plan.table, importSourceId: plan.importSourceId, contentHash: plan.contentHash,
+            });
+            this.tallyDedup(dedup, verdict);
+            if (mappingPreview.length < PREVIEW_SAMPLE_SIZE) {
+                mappingPreview.push(plan);
+            }
+        }
+        // projektscope-feloldások (a forrás distinct project-jeire), preview-only.
+        const projectScopes = await this.previewProjectScopes(data, request);
+        return {
+            source: request.source ?? 'claude-mem',
+            from: this.resolveFrom(request),
+            counts: data.counts,
+            byType: byType,
+            dedup: dedup,
+            projectScopes: projectScopes,
+            mappingPreview: mappingPreview,
+            warnings: warnings,
+        };
+    }
+    // =========================================================================
+    // (2) MAP — override (dsgn-009 §5.2) — STILL nem ír
+    // =========================================================================
+    /**
+     * `map` (dsgn-009 §5.2) — a §4 default leképezés felülírása (byType / byId / scope / includePrompts)
+     * + a teljes feloldott leképezési terv visszaadása. STILL nem ír. A scope-resolve itt is read-only
+     * (a tényleges auto-create a `run`-ban történik). Az `appliedOverrides` echo az átláthatósághoz.
+     */
+    async map(request) {
+        const data = await this.readSource(request);
+        const warnings = [...data.warnings];
+        const uncertainty = [];
+        const plans = [];
+        for (const record of data.records) {
+            plans.push(await this.buildPlan({
+                record: record, request: request, allowCreateScope: false, uncertainty: uncertainty,
+            }));
+        }
+        return {
+            source: request.source ?? 'claude-mem',
+            from: this.resolveFrom(request),
+            plans: plans,
+            appliedOverrides: request.overrides ?? {},
+            warnings: warnings,
+        };
+    }
+    // =========================================================================
+    // (3) RUN / IMPORT — írás egy batchId alatt (dsgn-009 §5.3)
+    // =========================================================================
+    /**
+     * `run` (dsgn-009 §5.3) — a tényleges beszúrás egy **import-batch** (`batchId` = `ingestRunId`)
+     * alatt. Rekordonként: dedup → SKIP (NEM embeddel) VAGY map + persist (`importSource`/
+     * `importSourceId`/`contentHash`/`ingestRunId`) + embed (MP-2 `embedAndPersist`). A scope-resolve
+     * itt auto-create-elhet (`createdBy='agent-write'` a MP-3-ban). A per-rekord hiba NEM buktatja a
+     * batch-et (`status:'partial-failed'`, strukturált `errors[]`). MON-esemény a végén.
+     */
+    async run(request) {
+        const batchId = crypto.randomUUID();
+        const data = await this.readSource(request);
+        const byTable = {};
+        const errors = [];
+        const uncertaintyNotes = [];
+        let ingested = 0;
+        let skipped = 0;
+        let failed = 0;
+        // Embedding-költség pillanatkép a batch ELŐTT (a delta a batch embed-költsége — BFR-AM-007).
+        const costBefore = embedding_1.FAM_EmbeddingCost_ControlService.getInstance().getStats().totalEstimatedCostUsd;
+        for (const record of data.records) {
+            try {
+                const plan = await this.buildPlan({
+                    record: record, request: request, allowCreateScope: true, uncertainty: uncertaintyNotes,
+                });
+                const verdict = await fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.getInstance().verdictFor({
+                    record: record, table: plan.table, importSourceId: plan.importSourceId, contentHash: plan.contentHash,
+                });
+                if (verdict !== 'import') {
+                    // A skip-eltek NEM embeddelődnek (cost-takarékosság — dsgn-009 §5.3 / §9.3).
+                    skipped++;
+                    continue;
+                }
+                await this.persistAndEmbed({ record: record, plan: plan, batchId: batchId });
+                ingested++;
+                byTable[plan.table] = (byTable[plan.table] ?? 0) + 1;
+            }
+            catch (error) {
+                failed++;
+                const famError = await errors_control_service_1.FAM_Error_ControlService.getInstance().emit({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.impMap,
+                    message: `Egy claude-mem rekord importja sikertelen (entity='${record.entity}', `
+                        + `id='${record.sourceRowId}'). A batch a többi rekorddal folytatódik (partial-failed).`,
+                    cause: error,
+                    context: { operation: 'import-run', runId: batchId },
+                });
+                errors.push({
+                    errorCode: fsm_dynamo_1.DyFM_Error.getErrorCode(famError),
+                    message: fsm_dynamo_1.DyFM_Error.getErrorMessage(famError),
+                    importSourceId: fam_target_mapping_util_1.FAM_TargetMapping_Util.importSourceId(record),
+                });
+            }
+        }
+        const costAfter = embedding_1.FAM_EmbeddingCost_ControlService.getInstance().getStats().totalEstimatedCostUsd;
+        const status = this.runStatus(ingested, failed);
+        const result = {
+            ok: status !== 'failed',
+            batchId: batchId,
+            ingested: ingested,
+            skipped: skipped,
+            failed: failed,
+            byTable: byTable,
+            embedTokenCost: Math.max(costAfter - costBefore, 0),
+            status: status,
+            uncertaintyNotes: this.dedupUncertainty(uncertaintyNotes),
+            errors: errors,
+        };
+        this.emitMonEvent({ batchId: batchId, data: data, result: result });
+        return result;
+    }
+    // =========================================================================
+    // (4) ROLLBACK — pontosan egy batch soft-delete (dsgn-009 §5.4)
+    // =========================================================================
+    /**
+     * `rollback` (dsgn-009 §5.4) — pontosan EGY import-batch összes entry-jének soft-delete-elése az
+     * `ingestRunId == batchId` szűrőre, MINDEN fő táron. Más batch-et NEM érint. Idempotens: már
+     * visszavont batch → `reverted:0`. A soft-delete a `DyNTS_DataService.deleteData(id, false)`-on át
+     * (archív → history, dsgn-001 §8).
+     */
+    async rollback(set) {
+        if (!set.batchId || !set.batchId.trim().length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impMap,
+                message: 'A `rollback_import`-hoz `batchId` kötelező (egy korábbi import-batch azonosítója).',
+                issuer: this.issuer,
+                context: { operation: 'import-rollback' },
+            });
+        }
+        const table = {};
+        let reverted = 0;
+        // Minden fő tár: a batch-hez tartozó (importSource + ingestRunId) entry-k soft-delete-je.
+        for (const registryEntry of this.allRegistryEntries()) {
+            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+            const filter = {
+                importSource: fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.IMPORT_SOURCE,
+                ingestRunId: set.batchId,
+            };
+            const batchEntries = await dataService.findHydratableList(filter);
+            for (const entry of batchEntries) {
+                if (entry._id) {
+                    await dataService.deleteData(entry._id, false);
+                    reverted++;
+                    table[registryEntry.table] = (table[registryEntry.table] ?? 0) + 1;
+                }
+            }
+        }
+        return { ok: true, batchId: set.batchId, reverted: reverted, table: table };
+    }
+    // =========================================================================
+    // forrás-olvasás (SP-11.1 reader-dispatch)
+    // =========================================================================
+    /** A forrás-csatorna feloldása (`from`; default export-JSON). */
+    resolveFrom(request) {
+        return request.from ?? fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.exportJson;
+    }
+    /** A `includePrompts` feloldása (override > request; default false). */
+    resolveIncludePrompts(request) {
+        if (request.overrides && typeof request.overrides.includePrompts === 'boolean') {
+            return request.overrides.includePrompts;
+        }
+        return request.includePrompts === true;
+    }
+    /**
+     * A forrás beolvasása a `from` szerinti reader-en (SP-11.1 dispatch). Az `includePrompts`-ot az
+     * override-ral összevontan adja át. A forrás-hibát a reader strukturáltan dobja (`FAM-IMP-SOURCE-001`).
+     */
+    async readSource(request) {
+        const from = this.resolveFrom(request);
+        const includePrompts = this.resolveIncludePrompts(request);
+        const path = request.path ?? '';
+        switch (from) {
+            case fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.exportJson:
+                return fam_claude_mem_export_reader_service_1.FAM_ClaudeMemExportReader_Service.getInstance().read({ path: path, includePrompts: includePrompts });
+            case fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.sqlite:
+                return fam_claude_mem_sqlite_reader_service_1.FAM_ClaudeMemSqliteReader_Service.getInstance().read({ path: path, includePrompts: includePrompts });
+            case fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.workerApi:
+                return fam_claude_mem_worker_reader_service_1.FAM_ClaudeMemWorkerReader_Service.getInstance()
+                    .read({ baseUrl: path, includePrompts: includePrompts });
+            default:
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                    message: `Ismeretlen claude-mem forrás-csatorna: '${from}'. Megengedett: export-json | sqlite | worker-api.`,
+                    issuer: this.issuer,
+                    context: { operation: 'import-read-source' },
+                });
+        }
+    }
+    // =========================================================================
+    // leképezési-terv építés (SP-11.2: target-mapping + scope-resolve)
+    // =========================================================================
+    /**
+     * Egy rekord teljes leképezési terve (SP-11.2). A target-mapping (`FAM_TargetMapping_Util`) +
+     * a content-kompozíció + a `contentHash` + a `project`→canonical scope (MP-3). A `allowCreateScope`
+     * `false` (preview/map) → read-only scope-feloldás (auto-create kihagyva), `true` (run) →
+     * `resolveForWrite` (auto-create-elhet). A scope-feloldás van-match-bizonytalansága az `uncertainty`
+     * gyűjtőbe (NEM hiba).
+     */
+    async buildPlan(set) {
+        const target = fam_target_mapping_util_1.FAM_TargetMapping_Util.resolveTarget({ record: set.record, overrides: set.request.overrides });
+        const content = fam_target_mapping_util_1.FAM_TargetMapping_Util.composeContent(set.record);
+        const contentHash = fam_import_content_hash_util_1.FAM_ImportContentHash_Util.hash({
+            narrative: set.record.narrative, text: set.record.text, facts: set.record.facts,
+        });
+        const importSourceId = fam_target_mapping_util_1.FAM_TargetMapping_Util.importSourceId(set.record);
+        const scopeResolve = await this.resolveScopeForRecord({
+            record: set.record, request: set.request, allowCreateScope: set.allowCreateScope,
+        });
+        for (const note of scopeResolve.uncertaintyNotes) {
+            set.uncertainty.push(note);
+        }
+        return {
+            importSourceId: importSourceId,
+            entity: set.record.entity,
+            sourceType: set.record.type,
+            table: target.table,
+            kind: target.kind,
+            tags: target.tags,
+            content: content,
+            contentHash: contentHash,
+            scopePath: scopeResolve.scopePath,
+            project: set.record.project,
+            uncertaintyNotes: scopeResolve.uncertaintyNotes,
+        };
+    }
+    /**
+     * A `project` → canonical scope feloldása (dsgn-002 §3.2, dsgn-009 §4). A scope a raw `project`
+     * stringből (`project`-layer) — VAGY az override-ból (`scope['project:<name>']`). `allowCreateScope:
+     * false` (preview/map) → read-only feloldás: ha nem oldható fel meglévő scope-pá, üres scopePath +
+     * uncertainty (NEM hoz létre). `allowCreateScope: true` (run) → `resolveForWrite` (auto-create-elhet).
+     * Project nélküli rekord → üres scopePath (a memory-tár scope nélkül is írható import-provenance-szal).
+     */
+    async resolveScopeForRecord(set) {
+        const rawScope = this.rawScopeForRecord(set.record, set.request);
+        if (!rawScope || !rawScope.length) {
+            return { scopePath: [], uncertaintyNotes: [] };
+        }
+        if (set.allowCreateScope) {
+            // run: a write-path teljes feloldása (auto-create-elhet — createdBy='agent-write' a MP-3-ban).
+            const resolve = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().resolveForWrite(rawScope);
+            return { scopePath: resolve.scopePath, uncertaintyNotes: resolve.uncertaintyNotes };
+        }
+        // preview/map: read-only — a read-expand-szerű feloldás NEM hoz létre scope-ot. A trace-feloldáson
+        // át döntjük el, feloldható-e biztosan; ha nem, üres scopePath + a bizonytalanság jelezve.
+        return this.previewResolveScope(rawScope);
+    }
+    /**
+     * Egy rekord nyers scope-lánca: az override `scope['project:<name>']` explicit `scopePath`-ja
+     * elsőbbséget élvez; egyébként a raw `project` egyetlen `project`-layer-ként. Project nélkül undefined.
+     */
+    rawScopeForRecord(record, request) {
+        if (!record.project) {
+            return undefined;
+        }
+        const overrideKey = `project:${record.project}`;
+        const override = request.overrides?.scope?.[overrideKey];
+        if (override && override.scopePath.length) {
+            return override.scopePath.map((layer) => ({ layer: layer.layer, rawName: layer.rawName }));
+        }
+        return [{ layer: PROJECT_SCOPE_LAYER, rawName: record.project }];
+    }
+    /**
+     * Read-only (preview/map) scope-feloldás: a MP-3 `traceResolution`-on át eldönti, feloldható-e a
+     * scope-lánc biztosan (`confident` minden layeren). Ha igen → a feloldott meglévő scope-lánc; ha
+     * nem (no-match / ambiguous), NEM hoz létre scope-ot → üres scopePath + uncertainty (a preview
+     * jelzi, a user a `map`-ben adhat explicit scope-ot). SOHA nem mutál.
+     */
+    async previewResolveScope(rawScope) {
+        const trace = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().traceResolution(rawScope, 'write-resolve');
+        const allConfident = trace.steps.length > 0 && trace.steps.every((step) => step.classification === 'confident');
+        if (!allConfident) {
+            const note = {
+                rawToken: rawScope.map((layer) => layer.rawName).join('>'),
+                normalizedForm: trace.steps.map((step) => step.normalizedForm).join('>'),
+                resolvedTo: '',
+                confidence: 0,
+                matchSource: 'scope-name',
+                alternatives: [],
+            };
+            return { scopePath: [], uncertaintyNotes: [note] };
+        }
+        // Minden layer confident → a döntött canonical-ek nem hordoznak scopeId-t a trace-ben; a
+        // preview a confidence-t jelzi, a tényleges scopeId-feloldás a run-ban (write-resolve) történik.
+        return { scopePath: [], uncertaintyNotes: [] };
+    }
+    /**
+     * A forrás distinct project-jeinek preview-feloldása (dsgn-009 §5.1 `projectScopes`). Read-only:
+     * a `traceResolution` confidence-e dönt (high/uncertain). SOHA nem hoz létre scope-ot.
+     */
+    async previewProjectScopes(data, request) {
+        const projects = new Set();
+        for (const record of data.records) {
+            if (record.project) {
+                projects.add(record.project);
+            }
+        }
+        for (const session of data.sessions) {
+            if (session.project) {
+                projects.add(session.project);
+            }
+        }
+        const result = [];
+        for (const project of projects) {
+            const rawScope = this.rawScopeForRecord({ project: project }, request) ?? [{ layer: PROJECT_SCOPE_LAYER, rawName: project }];
+            const trace = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().traceResolution(rawScope, 'write-resolve');
+            const confident = trace.steps.length > 0 && trace.steps.every((step) => step.classification === 'confident');
+            result.push({
+                project: project,
+                resolvedScopeId: null,
+                confidence: confident ? 'high' : 'uncertain',
+                note: confident ? undefined
+                    : 'A scope nem oldható fel biztosan — a `run` auto-regisztrál egy új scope-ot, '
+                        + 'vagy adj explicit `scopePath`-t a `map` lépésben (`overrides.scope`).',
+            });
+        }
+        return result;
+    }
+    // =========================================================================
+    // persist + embed (SP-11.3 írás)
+    // =========================================================================
+    /**
+     * Egy rekord persistálása + embeddelése a leképezési terv szerint (SP-11.3). A `FAM_Entry` a
+     * mapping-content + tags + kind + scope + a provenance-/dedup-mezőkkel (`importSource`/
+     * `importSourceId`/`contentHash`/`ingestRunId`=batchId, `addedBy='import'`, `source.type='import'`).
+     * A memory-tárnál a session-info (`sessionId`/`runId`) is hidratálva. Mentés UTÁN auto-embed (MP-2).
+     */
+    async persistAndEmbed(set) {
+        const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(set.plan.table);
+        if (!registryEntry) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impMap,
+                message: `A leképezett cél-tár nem fogad tartalom-importot: '${set.plan.table}'.`,
+                issuer: this.issuer,
+                context: { operation: 'import-persist', table: set.plan.table },
+            });
+        }
+        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const source = {
+            type: 'import',
+            path: set.record.filesModified[0] ?? undefined,
+            locator: set.plan.importSourceId,
+        };
+        const entry = new fam_entry_data_model_1.FAM_Entry({
+            table: set.plan.table,
+            kind: set.plan.kind,
+            tags: set.plan.tags,
+            content: set.plan.content,
+            contentHash: set.plan.contentHash,
+            scopePath: set.plan.scopePath,
+            embeddingStatus: 'pending',
+            addedBy: 'import',
+            source: source,
+            sourceFilePath: set.record.filesModified[0] ?? undefined,
+            ingestRunId: set.batchId,
+            importSource: fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.IMPORT_SOURCE,
+            importSourceId: set.plan.importSourceId,
+            ...this.memoryFields(set.record, set.plan.table),
+        });
+        const saved = await dataService.saveData(entry);
+        await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().embedAndPersist({
+            table: set.plan.table, entry: saved, callType: 'embed-write',
+        });
+    }
+    /**
+     * A memory-tár session-hidratálása (dsgn-009 §4): a `sessionId`/`runId` per-tár memory-mezők a
+     * forrás session-azonosítóiból. Csak a `memory` tárnál releváns (a per-tár mezők máshol nincsenek);
+     * a Mongo a deklarálatlan mezőt nem írja, de defenzíven csak a memory-tárra adjuk hozzá.
+     */
+    memoryFields(record, table) {
+        if (table !== fam_table_type_enum_1.FAM_Table.memory) {
+            return {};
+        }
+        const fields = {};
+        if (record.sdkSessionId) {
+            fields.sessionId = record.sdkSessionId;
+        }
+        if (record.claudeSessionId) {
+            fields.runId = record.claudeSessionId;
+        }
+        return fields;
+    }
+    // =========================================================================
+    // helpers
+    // =========================================================================
+    /** A dedup-verdikt számlálók aggregálása a preview-hoz. */
+    tallyDedup(dedup, verdict) {
+        if (verdict === 'import') {
+            dedup.willImport++;
+        }
+        else if (verdict === 'skip-existing') {
+            dedup.willSkipExisting++;
+        }
+        else {
+            dedup.willSkipDuplicateContent++;
+        }
+    }
+    /** A run-állapot: minden bukott → `failed`; van bukott de van beírt is → `partial-failed`; egyébként `ok`. */
+    runStatus(ingested, failed) {
+        if (failed && !ingested) {
+            return 'failed';
+        }
+        return failed ? 'partial-failed' : 'ok';
+    }
+    /** A bizonytalansági jegyzetek dedup-ja (rawToken+resolvedTo szerint) — a UI ne ismételjen. */
+    dedupUncertainty(notes) {
+        const seen = new Set();
+        const result = [];
+        for (const note of notes) {
+            const key = `${note.rawToken}→${note.resolvedTo}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                result.push(note);
+            }
+        }
+        return result;
+    }
+    /** A 6 fő tár store-registry bejegyzései (a rollback minden tárán végigmegy). */
+    allRegistryEntries() {
+        const 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,
+        ];
+        const entries = [];
+        for (const table of tables) {
+            const entry = embedding_1.FAM_StoreRegistry_Util.getEntry(table);
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+        return entries;
+    }
+    /**
+     * A `famImport` MON-esemény a batch végén (dsgn-009 §5.3; a CCAP `ragIngest` mintára). MVP1: a
+     * `DyFM_Log.info`-n strukturált payload-dal (a Logs-routing wiring KÉSŐBBI MP — NEM rántjuk előre,
+     * az ingest MON-eseménnyel azonos minta). A payload shape a dsgn-009 §5.3 szerinti.
+     */
+    emitMonEvent(set) {
+        fsm_dynamo_1.DyFM_Log.info('[famImport]', {
+            event: 'famImport',
+            source: 'claude-mem',
+            from: set.data.from,
+            batchId: set.batchId,
+            chunkCount: set.result.ingested + set.result.skipped + set.result.failed,
+            ingested: set.result.ingested,
+            skipped: set.result.skipped,
+            failed: set.result.failed,
+            byTable: set.result.byTable,
+            embedTokenCost: set.result.embedTokenCost,
+            status: set.result.status,
+        });
+    }
+}
+exports.FAM_ClaudeMemImport_ControlService = FAM_ClaudeMemImport_ControlService;

package/build/src/_modules/migration/_services/fam-claude-mem-sqlite-reader.service.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ClaudeMemSqliteReader_Service = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const better_sqlite3_1 = tslib_1.__importDefault(require("better-sqlite3"));
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_claude_mem_source_type_enum_1 = require("../_enums/fam-claude-mem-source.type-enum");
+const fam_claude_mem_normalize_util_1 = require("../_collections/fam-claude-mem-normalize.util");
+/**
+ * `FAM_ClaudeMemSqliteReader_Service` (SP-11.1) — a **SQLite reader** (`from=sqlite`, BFR-AM-009
+ * fallback). A claude-mem `~/.claude-mem/claude-mem.db` táblái (`observations` / `session_summaries` /
+ * `user_prompts` / `sdk_sessions`) közvetlen, read-only olvasása egy IZOLÁLT, build-only natív
+ * függőséggel (`better-sqlite3`) — a Dynamo-stack Mongo-alapú, ezért a SQLite a projekt-lokális
+ * adapterben él. A reader UGYANAZT a normalizált `FAM_ClaudeMemRecord` halmazt adja, mint az
+ * export-JSON ugyanarra a tartalomra (paritás — dsgn-009 §9.2).
+ *
+ * **Csere-pont (BFR-AM-009, MP-15):** amikor a bedrock `DyNTS_Sqlite_Reader_Util` landol, CSAK ennek a
+ * service-nek a tábla-olvasó belseje cserélődik (a `readTable`), az adapter-interfész (`read`) és a
+ * normalizáló-szerződés (`FAM_ClaudeMemNormalize_Util`) változatlan marad — a dedup/mapping (SP-11.2)
+ * érintetlen.
+ *
+ * **Fail-soft (dsgn-009 §9):** fájl-hiány / megnyitás-hiba / hiányzó tábla → tiszta strukturált hiba
+ * (`FAM-IMP-SOURCE-001`), NEM hang/crash. A DB mindig zárul (try/finally).
+ */
+class FAM_ClaudeMemSqliteReader_Service {
+    static _instance;
+    /** Default issuer (a forrás-hibák issuer-éhez; dsgn-008). */
+    issuer = 'FAM_ClaudeMemSqliteReader_Service';
+    static getInstance() {
+        if (!FAM_ClaudeMemSqliteReader_Service._instance) {
+            FAM_ClaudeMemSqliteReader_Service._instance = new FAM_ClaudeMemSqliteReader_Service();
+        }
+        return FAM_ClaudeMemSqliteReader_Service._instance;
+    }
+    /**
+     * A SQLite DB read-only megnyitása + a 4 tábla olvasása + normalizálás (SP-11.1). A `path` a
+     * `.db` fájl útvonala. Megnyitás-/olvasás-hiba → `FAM-IMP-SOURCE-001` (deskriptív). A hiányzó
+     * táblát üres listaként kezeli + warning (a séma drift-elhet, nem-néma drop).
+     */
+    read(set) {
+        if (!set.path || !set.path.trim().length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: 'A SQLite importhoz `path` kötelező (a claude-mem `.db` fájl útvonala, '
+                    + 'pl. `~/.claude-mem/claude-mem.db`).',
+                issuer: this.issuer,
+                context: { operation: 'import-read-sqlite' },
+            });
+        }
+        if (!fs.existsSync(set.path)) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: `A claude-mem SQLite DB nem található: '${set.path}'.`,
+                issuer: this.issuer,
+                context: { operation: 'import-read-sqlite' },
+            });
+        }
+        const warnings = [];
+        let db = undefined;
+        try {
+            db = new better_sqlite3_1.default(set.path, { readonly: true, fileMustExist: true });
+            const observations = this.readTable(db, 'observations', warnings);
+            const summaries = this.readTable(db, 'session_summaries', warnings);
+            const prompts = this.readTable(db, 'user_prompts', warnings);
+            const sessions = this.readTable(db, 'sdk_sessions', warnings);
+            const normalized = fam_claude_mem_normalize_util_1.FAM_ClaudeMemNormalize_Util.normalizeAll({
+                from: fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.sqlite,
+                observations: observations.map((row) => this.hydrateObservation(row)),
+                summaries: summaries, prompts: prompts, sessions: sessions,
+                includePrompts: set.includePrompts,
+            });
+            normalized.warnings = [...warnings, ...normalized.warnings];
+            return normalized;
+        }
+        catch (error) {
+            // A normalizáló dobott FAM-hibát NEM csomagoljuk újra (már strukturált).
+            if (error && typeof error === 'object' && 'errorCode' in error) {
+                throw error;
+            }
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: `A claude-mem SQLite DB megnyitása/olvasása sikertelen: '${set.path}'.`,
+                issuer: this.issuer,
+                context: { operation: 'import-read-sqlite' },
+                cause: error,
+            });
+        }
+        finally {
+            if (db) {
+                db.close();
+            }
+        }
+    }
+    /**
+     * Egy tábla összes sorának read-only olvasása (a BFR-AM-009 bedrock-helper cserélheti). A hiányzó
+     * tábla NEM hiba (a séma drift-elhet) → warning + []. A `concepts`/`files_*` JSON-string-oszlopok
+     * a `hydrateObservation`-ben oldódnak fel (a SQLite skalár-oszlopokat ad vissza).
+     */
+    readTable(db, table, warnings) {
+        if (!this.tableExists(db, table)) {
+            warnings.push(`A '${table}' tábla nem létezik a SQLite DB-ben — üres listaként kezelve (séma-drift?).`);
+            return [];
+        }
+        const rows = db.prepare(`SELECT * FROM ${table}`).all();
+        return rows;
+    }
+    /** Egy tábla létezésének read-only ellenőrzése (`sqlite_master`). */
+    tableExists(db, table) {
+        const found = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(table);
+        return Boolean(found);
+    }
+    /**
+     * Egy SQLite observation-sor hidratálása: a `concepts`/`files_read`/`files_modified` a SQLite-ban
+     * JSON-string-oszlopként élnek (a Mongo/export tömb-ekvivalense) — itt tömbökre parse-oljuk, hogy
+     * a normalizált rekord a 3 forrásra azonos legyen (paritás). Hibás JSON → üres tömb (defenzív).
+     */
+    hydrateObservation(row) {
+        return {
+            ...row,
+            concepts: this.parseJsonArray(row.concepts),
+            files_read: this.parseJsonArray(row.files_read),
+            files_modified: this.parseJsonArray(row.files_modified),
+        };
+    }
+    /** Egy érték string-tömbként: már-tömb → ahogy van; JSON-string → parse; egyéb → []. */
+    parseJsonArray(value) {
+        if (Array.isArray(value)) {
+            return value.filter((item) => typeof item === 'string');
+        }
+        if (typeof value !== 'string' || !value.trim().length) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(value);
+            return Array.isArray(parsed) ? parsed.filter((item) => typeof item === 'string') : [];
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.FAM_ClaudeMemSqliteReader_Service = FAM_ClaudeMemSqliteReader_Service;