@futdevpro/fdp-agent-memory 1.1.21 → 1.1.112

package/build/src/_modules/ingest/_services/fam-ingest.control-service.js

@@ -19,9 +19,11 @@ const fam_content_hash_util_1 = require("../_collections/fam-content-hash.util")
 const fam_git_repo_util_1 = require("../_collections/fam-git-repo.util");
 const fam_scan_reconcile_util_1 = require("../_collections/fam-scan-reconcile.util");
 const fam_secret_content_util_1 = require("../_collections/fam-secret-content.util");
+const fam_frontmatter_util_1 = require("../_collections/fam-frontmatter.util");
 const fam_project_identity_util_1 = require("../_collections/fam-project-identity.util");
 const fam_scan_path_util_1 = require("../_collections/fam-scan-path.util");
 const fam_scan_progress_util_1 = require("../_collections/fam-scan-progress.util");
+const fam_scan_progress_sink_service_1 = require("../../../_collections/fam-scan-progress-sink.service");
 const fam_scan_summary_util_1 = require("../_collections/fam-scan-summary.util");
 const scope_reference_2 = require("../../scope-reference");
 const fam_reference_data_model_1 = require("../../../_models/data-models/fam-reference.data-model");
@@ -59,6 +61,16 @@ class FAM_Ingest_ControlService {
         const sample = content.length > 8192 ? content.slice(0, 8192) : content;
         return sample.indexOf(String.fromCharCode(0)) !== -1;
     }
+    /**
+     * Tábla-vezérelt ADDITÍV (accumulate-only) szabály (user-FR 2026-06-24): a `memory` tár MINDIG content-addressed
+     * additív — a memória-bejegyzések sosem „íródnak felül azonos location-nél", így a kompaktálás-előtti állapot
+     * a forrás zsugorodása UTÁN is megmarad a FAM-ban (vesztességmentes superset). A többi tár (codebase/documents/
+     * rules/...) a szokásos `(fájl, chunkIndex)` delta-t használja; rájuk a `preserveHistory` request-flag kérhet
+     * explicit additívot. Pure + statikus (tesztelhető).
+     */
+    static isAccumulateOnly(table) {
+        return table === fam_table_type_enum_1.FAM_Table.memory;
+    }
     /** Default issuer az ingest-műveletekhez. */
     issuer = 'FAM_Ingest_ControlService';
     static getInstance() {
@@ -180,7 +192,7 @@ class FAM_Ingest_ControlService {
         });
         runId = openedRun._id ?? runId;
         // (4) Per-fájl feldolgozás (flow-limit kötegekben; a per-fájl hiba NEM buktatja a run-t).
-        const verdicts = { new: 0, modified: 0, equal: 0, deleted: 0 };
+        const verdicts = { new: 0, modified: 0, equal: 0, deleted: 0, superseded: 0 };
         const errors = [];
         let chunkCount = 0;
         const flowLimit = await this.resolveFlowLimit(canonicalScope);
@@ -195,12 +207,21 @@ class FAM_Ingest_ControlService {
             ? 0
             : fam_cooldown_util_1.FAM_Cooldown_Util.resolveMs((await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('scan.sectionCooldownMs', { scopePath: canonicalScope })).value);
         let lastProgressAt = startedAt;
+        // Sub-progress (user-FR 2026-06-22): a felderítés→embedding közti csend kitöltése — mit gyűjtöttünk be +
+        // hogyan route-oltuk (mely tárakba), MIELŐTT a throttle-olt feldolgozás-sorok elindulnak.
+        if (!isDryRun && total > 0) {
+            const scopeLabel = canonicalScope.map((ref) => ref.canonicalName).join(' > ') || '(globális)';
+            fsm_dynamo_1.DyFM_Log.info(`[famIngest] [${scopeLabel}] felderítés kész: ${total} fájl begyűjtve `
+                + `(${discovery.skippedFiles.length} kihagyva, tárak: ${discovery.tables.map((table) => String(table)).join('+') || '—'}) `
+                + '→ embedding indul');
+        }
         for (let i = 0; i < total; i += flowLimit) {
             const batch = discovery.routedFiles.slice(i, i + flowLimit);
             const results = await Promise.all(batch.map((file) => this.processFile({
                 file: file, runId: runId, scopePath: canonicalScope,
                 resolvedRoot: discovery.resolvedRoot,
                 dryRun: isDryRun, issuer: issuer, errors: errors,
+                preserveHistory: request.preserveHistory === true,
             })));
             for (const result of results) {
                 if (!result) {
@@ -215,10 +236,17 @@ class FAM_Ingest_ControlService {
             const now = Date.now();
             if (!isDryRun && (processed >= total || now - lastProgressAt >= progressIntervalMs)) {
                 lastProgressAt = now;
+                const scopeLeaf = canonicalScope.length ? canonicalScope[canonicalScope.length - 1].canonicalName : '';
                 fsm_dynamo_1.DyFM_Log.info(fam_scan_progress_util_1.FAM_ScanProgress_Util.progressLine({
+                    scopeLabel: scopeLeaf || undefined,
                     processed: processed, total: total, chunkCount: chunkCount,
                     verdicts: verdicts, elapsedSeconds: (now - startedAt) / 1000,
                 }));
+                // Sub-progress sink (user-FR): a within-project haladás a scan-job status-ába → a thin-CLI poll is látja.
+                fam_scan_progress_sink_service_1.FAM_ScanProgress_Sink.set({
+                    scopeLabel: scopeLeaf, processed: processed, total: total, chunkCount: chunkCount,
+                    pct: total ? Math.round((processed / total) * 100) : 100, updatedAt: now,
+                });
             }
             // Szekció-cooldown: a batch-ek KÖZÉ (NEM az utolsó után) — opcionális gép-tehermentesítő szünet.
             if (sectionCooldownMs > 0 && processed < total) {
@@ -228,7 +256,11 @@ class FAM_Ingest_ControlService {
         // (4b) Törölt-fájl reconciliation (whole-file orphan) — CSAK folder/project scan (a `scan-file`
         // egyetlen fájlt céloz, nem reconciliál). A lemezről eltűnt fájlok chunkjai soft-delete-elődnek; a
         // számuk a `verdicts.deleted`-be (a per-fájl, fájlon-belüli `deleted`-ek mellé).
-        if (request.operation !== 'scan-file') {
+        // ADDITÍV mód (user-FR 2026-06-22/24): `preserveHistory` request-flag VAGY a `memory` tár (tábla-vezérelt) →
+        // a reconcile-törlés KIHAGYVA (a FAM superset-ként megtartja a forrásból eltűnt — pl. kompaktálódó memóriám —
+        // bejegyzéseit is; nincs destruktív felülírás). A `memory` ezért SOHA nem reconciliál, flag nélkül sem.
+        if (request.operation !== 'scan-file' && !request.preserveHistory
+            && !(request.tableOverride !== undefined && FAM_Ingest_ControlService.isAccumulateOnly(request.tableOverride))) {
             const reconcileIgnored = await this.resolveReconcileIgnored(canonicalScope);
             verdicts.deleted += await this.reconcileDeletedFiles({
                 discovery: discovery, scopePath: canonicalScope, issuer: issuer, dryRun: request.dryRun ?? false,
@@ -284,7 +316,7 @@ class FAM_Ingest_ControlService {
      * soft-delete). A per-fájl hiba `errors[]`-be (no-silent-failure) + `null` visszatérés (a run nem bukik).
      */
     async processFile(set) {
-        const table = set.file.route;
+        let table = set.file.route;
         try {
             const rawContent = fs.readFileSync(set.file.absolutePath, 'utf-8');
             // Tartalmi secret-redakció (user-FR): a forrásba hardcode-olt API-kulcs (sk-/AKIA/ghp_/PEM/JWT) a tárolt
@@ -294,7 +326,16 @@ class FAM_Ingest_ControlService {
             if (redaction.count > 0) {
                 fsm_dynamo_1.DyFM_Log.warn(`[famIngest] secret-redakció: ${redaction.count} token redaktálva (${set.file.relativePath})`);
             }
-            const content = redaction.text;
+            // MP-3 / F-A: fájl-fej `---`-frontmatter → ingest-irányítók + fejléc-mentes TÖRZS. Frontmatter nélkül NO-OP
+            // (`body===content`). A `table`-override (pl. `table: rules`) + `splitMode` + a per-entry rule-mezők innen jönnek.
+            const front = fam_frontmatter_util_1.FAM_Frontmatter_Util.parse(redaction.text);
+            const directives = front.directives;
+            const overrideTable = this.resolveDirectiveTable(directives.table);
+            if (overrideTable) {
+                table = overrideTable;
+            }
+            const splitMode = directives.splitMode === true ? 'heading' : (directives.splitMode || undefined);
+            const content = front.body;
             // FAM-REV-064 bináris-tartalom guard: a denylist-en átcsúszott, ismeretlen-kiterjesztésű bináris
             // (null-byte az első ~8KB-ban) NE kerüljön a generic chunkerbe (szemét-chunk ellen). Skip → 0 chunk.
             if (FAM_Ingest_ControlService.isLikelyBinary(content)) {
@@ -302,6 +343,7 @@ class FAM_Ingest_ControlService {
             }
             const chunks = await fam_chunker_control_service_1.FAM_Chunker_ControlService.getInstance().chunkFile({
                 content: content, relativePath: set.file.relativePath, table: table, scopePath: set.scopePath,
+                splitMode: splitMode,
             });
             const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(table);
             if (!registryEntry) {
@@ -311,11 +353,17 @@ class FAM_Ingest_ControlService {
             // Existing-by-key betöltés a KANONIKUS abszolút útvonalon (FAM-REV-050) — a scan-root-független
             // fájl-identitás, így a delta bármely scan-gyökérről ugyanazt a fájlt matcheli (nincs duplikáció).
             const existing = await this.loadExistingChunks(dataService, set.file.absolutePath, set.scopePath);
-            const deltaItems = fam_delta_compare_util_1.FAM_DeltaCompare_Util.compare(chunks, existing);
+            // ADDITÍV (content-addressed) delta → a régi (kompaktálás-előtti) tartalom MEGMARAD, sose `deleted`/`modified`
+            // (a FAM a memória minden valaha-látott állapotának vesztességmentes uniója). TÁBLA-VEZÉRELT (user-FR
+            // 2026-06-24): a `memory` tár MINDIG additív (a „felülírás azonos location-nél" csak kódbázis/dok/rules);
+            // a `preserveHistory` request-flag pedig bármely tárra explicit additív szkent kérhet.
+            const accumulateOnly = set.preserveHistory === true || FAM_Ingest_ControlService.isAccumulateOnly(table);
+            const deltaItems = fam_delta_compare_util_1.FAM_DeltaCompare_Util.compare(chunks, existing, accumulateOnly);
             if (!set.dryRun) {
                 await this.applyVerdicts({
                     deltaItems: deltaItems, file: set.file, table: table, runId: set.runId,
                     scopePath: set.scopePath, root: set.resolvedRoot, dataService: dataService,
+                    directives: directives,
                 });
             }
             return {
@@ -373,6 +421,10 @@ class FAM_Ingest_ControlService {
                             // re-embed nélkül (a friss chunk charStart/charEnd/sor-pozíciója felülír, ha eltér).
                             await set.dataService.backfillPosition(item.existingId, item.chunk.position);
                         }
+                        // Git-provenance backfill (user-FR 2026-06-22): a CSAK-metaadat frissítés — a git-provenance
+                        // feature ELŐTT ingestelt korpusz `equal`-chunkjai is megkapják a repoUrl/repoRelativePath/
+                        // repoBranch-et RE-EMBED NÉLKÜL (a control-service számolja, így nincs data-service↔ingest ciklus).
+                        await set.dataService.backfillGitProvenance(item.existingId, fam_git_repo_util_1.FAM_GitRepo_Util.sourceFieldsFor(set.file.absolutePath));
                     }
                     catch {
                         // best-effort metaadat-frissítés — a content már naprakész (equal), nem eszkaláljuk.
@@ -384,7 +436,7 @@ class FAM_Ingest_ControlService {
                         await this.persistAndEmbed({
                             chunk: item.chunk, existingId: item.existingId, contentHash: item.contentHash,
                             file: set.file, table: set.table, runId: set.runId, scopePath: set.scopePath,
-                            root: set.root, dataService: set.dataService,
+                            root: set.root, dataService: set.dataService, directives: set.directives,
                         });
                     }
                 }
@@ -398,12 +450,21 @@ class FAM_Ingest_ControlService {
                 }
                 continue;
             }
+            if (item.verdict === 'superseded') {
+                // dsgn-013 §6 (MAM F4): a fájl régi, már átírt tartalma — NEM törlés (a content + vektor MEGMARAD a
+                // poolban is, cold-kereshető), csak `superseded=true` jelölés → a memory-ranking penalizálja (a friss
+                // verzió fölébe kerül). A pool-ból NEM vesszük ki (a penalty süllyeszti; a dormancy idővel de-hidratálja).
+                if (item.existingId) {
+                    await set.dataService.setSuperseded(item.existingId, true);
+                }
+                continue;
+            }
             // new / modified → upsert + embed (a `chunk` itt sosem null).
             if (item.chunk) {
                 await this.persistAndEmbed({
                     chunk: item.chunk, existingId: item.existingId, contentHash: item.contentHash,
                     file: set.file, table: set.table, runId: set.runId, scopePath: set.scopePath,
-                    root: set.root, dataService: set.dataService,
+                    root: set.root, dataService: set.dataService, directives: set.directives,
                 });
             }
         }
@@ -437,6 +498,9 @@ class FAM_Ingest_ControlService {
             addedBy: 'scan',
             ingestRunId: set.runId,
         });
+        // MP-3 / F-A: a frontmatter per-entry rule-mezőit (importance/userApproved/ruleScope/…) + tageket rákötjük.
+        // CSAK definiált értékek (Object.assign-nal) — a nem-rules táron a nem-deklarált mezők úgyis nem persistálnak.
+        this.applyDirectiveFields(entry, set.directives);
         // Persist (saveData = upsert: meglévő `_id` → modify, hiányzó → insert).
         const saved = await set.dataService.saveData(entry);
         // Embed CSAK a new/modified-re (MP-2). Az embed-hiba az entry-t `error`-státuszba teszi +
@@ -445,6 +509,51 @@ class FAM_Ingest_ControlService {
             table: set.table, entry: saved, callType: 'embed-write',
         });
     }
+    /** A frontmatter `table:` direktíva → érvényes `FAM_Table` (ismeretlen → undefined, a file-routing marad). */
+    resolveDirectiveTable(raw) {
+        if (!raw) {
+            return undefined;
+        }
+        return Object.values(fam_table_type_enum_1.FAM_Table).find((value) => value === raw);
+    }
+    /**
+     * MP-3 / F-A: a frontmatter per-entry rule-mezőit + tageket az `FAM_Entry`-re köti (CSAK definiált értékek). A
+     * nem-`rules` táron a nem-deklarált mezők úgyis nem persistálnak (a dataParams.properties dönt), így ártalmatlan.
+     */
+    applyDirectiveFields(entry, directives) {
+        if (!directives) {
+            return;
+        }
+        const target = entry;
+        if (typeof directives.importance === 'number') {
+            target.importance = directives.importance;
+        }
+        if (typeof directives.userApproved === 'boolean') {
+            target.userApproved = directives.userApproved;
+        }
+        if (typeof directives.globalRule === 'boolean') {
+            target.globalRule = directives.globalRule;
+        }
+        if (directives.ruleScope) {
+            target.ruleScope = directives.ruleScope;
+        }
+        if (directives.ruleScopeTopic) {
+            target.ruleScopeTopic = directives.ruleScopeTopic;
+        }
+        if (directives.ruleId) {
+            target.ruleId = directives.ruleId;
+        }
+        if (directives.derivedFrom) {
+            target.derivedFrom = directives.derivedFrom;
+        }
+        if (directives.category) {
+            target.category = directives.category;
+        }
+        if (directives.tags && directives.tags.length) {
+            const existing = Array.isArray(entry.tags) ? entry.tags : [];
+            target.tags = [...new Set([...existing, ...directives.tags])];
+        }
+    }
     /**
      * A file-rendszer-összefoglaló (`knowledge`, kind `fs-summary`) generálása + idempotens upsert-je a scan után.
      * A `FAM_ScanSummary_Util` a mappastruktúrából építi a kereshető „mi van a projektben" szöveget. **Identitás:**
@@ -459,15 +568,16 @@ class FAM_Ingest_ControlService {
         }
         const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: set.issuer });
         const scopeLabel = set.scopePath.map((ref) => ref.canonicalName).join(' > ') || '(globális)';
-        const content = fam_scan_summary_util_1.FAM_ScanSummary_Util.build({
+        // NO-LOSS split (user-FR 2026-06-22): nagy fánál TÖBB, egyenlő részre bontva — minden fájl szerepel,
+        // semmit nem nyelünk le. Részenként EGY-EGY `knowledge`-entry (`chunkIndex` = rész-index).
+        const parts = fam_scan_summary_util_1.FAM_ScanSummary_Util.buildParts({
             scopeLabel: scopeLabel,
             root: set.discovery.resolvedRoot,
             relativePaths: set.discovery.routedFiles.map((file) => file.relativePath),
             skippedCount: set.discovery.skippedFiles.length,
             tables: set.discovery.tables.map((table) => String(table)),
         });
-        const contentHash = fam_content_hash_util_1.FAM_ContentHash_Util.hash(content);
-        // Meglévő összefoglaló a (source-type + scan-gyökér + levél-scope) identitáson.
+        // A meglévő összefoglaló-részek a (source-type + scan-gyökér + levél-scope) identitáson, rész-index szerint.
         const leafScopeId = set.scopePath.length ? set.scopePath[set.scopePath.length - 1].scopeId : undefined;
         const filter = {};
         filter['source.type'] = fam_scan_summary_util_1.FAM_ScanSummary_Util.SOURCE_TYPE;
@@ -477,33 +587,54 @@ class FAM_Ingest_ControlService {
             filter['scopePath.scopeId'] = leafScopeId;
         }
         const existing = await dataService.findHydratableList(filter);
-        const existingEntry = existing[0];
-        // Változatlan fájl-lista → NO-OP (nincs fölös re-embed).
-        if (existingEntry && existingEntry.contentHash === contentHash) {
-            return;
+        const existingByIndex = new Map();
+        for (const item of existing) {
+            existingByIndex.set(item.chunkIndex ?? 0, item); // régi egy-részes entry: chunkIndex undefined → 0
+        }
+        let changed = 0;
+        for (let index = 0; index < parts.length; index++) {
+            const partContent = parts[index];
+            const partHash = fam_content_hash_util_1.FAM_ContentHash_Util.hash(partContent);
+            const existingPart = existingByIndex.get(index);
+            if (existingPart?.contentHash === partHash) {
+                continue; // változatlan rész → NO-OP (nincs fölös re-embed)
+            }
+            const entry = new fam_entry_data_model_1.FAM_Entry({
+                _id: existingPart?._id,
+                table: fam_table_type_enum_1.FAM_Table.knowledge,
+                content: partContent,
+                contentHash: partHash,
+                embeddingStatus: 'pending',
+                scopePath: set.scopePath,
+                chunkIndex: index,
+                kind: fam_scan_summary_util_1.FAM_ScanSummary_Util.KIND,
+                tags: ['fs-summary', 'filesystem', 'scan-summary'],
+                weight: 2,
+                source: {
+                    type: 'scan-summary', root: set.discovery.resolvedRoot, absolutePath: set.discovery.resolvedRoot,
+                },
+                addedBy: 'scan',
+                ingestRunId: set.runId,
+            });
+            const saved = await dataService.saveData(entry);
+            await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().embedAndPersist({
+                table: fam_table_type_enum_1.FAM_Table.knowledge, entry: saved, callType: 'embed-write',
+            });
+            changed++;
+        }
+        // Fölös részek (egy korábbi, NAGYOBB összefoglaló most-már-nem-létező részei) → soft-delete (no-orphan).
+        let removed = 0;
+        for (const item of existing) {
+            if ((item.chunkIndex ?? 0) >= parts.length) {
+                await dataService.deleteData(item._id);
+                removed++;
+            }
+        }
+        if (changed > 0 || removed > 0) {
+            fsm_dynamo_1.DyFM_Log.info(`[famIngest] fs-summary (${scopeLabel}): ${parts.length} rész `
+                + `(${changed} írva/frissítve, ${removed} fölös törölve), ${set.discovery.routedFiles.length} fájl, `
+                + `${set.discovery.tables.length} tár`);
         }
-        const entry = new fam_entry_data_model_1.FAM_Entry({
-            _id: existingEntry?._id,
-            table: fam_table_type_enum_1.FAM_Table.knowledge,
-            content: content,
-            contentHash: contentHash,
-            embeddingStatus: 'pending',
-            scopePath: set.scopePath,
-            kind: fam_scan_summary_util_1.FAM_ScanSummary_Util.KIND,
-            tags: ['fs-summary', 'filesystem', 'scan-summary'],
-            weight: 2,
-            source: {
-                type: 'scan-summary', root: set.discovery.resolvedRoot, absolutePath: set.discovery.resolvedRoot,
-            },
-            addedBy: 'scan',
-            ingestRunId: set.runId,
-        });
-        const saved = await dataService.saveData(entry);
-        await embedding_1.FAM_EmbeddingPipeline_ControlService.getInstance().embedAndPersist({
-            table: fam_table_type_enum_1.FAM_Table.knowledge, entry: saved, callType: 'embed-write',
-        });
-        fsm_dynamo_1.DyFM_Log.info(`[famIngest] fs-summary ${existingEntry ? 'frissítve' : 'létrehozva'} `
-            + `(${scopeLabel}): ${set.discovery.routedFiles.length} fájl, ${set.discovery.tables.length} tár`);
     }
     /**
      * A scan-gyökér PROJEKT-IDENTITÁSA (git + `package.json`) → (a) kereshető `knowledge` „project-identity"
@@ -558,6 +689,15 @@ class FAM_Ingest_ControlService {
         // (b) reference-alias (a package-név + rövid alakok → a projekt scope-ja) — string/exact-match feloldás.
         if (leaf) {
             await this.persistProjectReference(identity, leaf, set.discovery.resolvedRoot, set.issuer);
+            // (c) kanonikus repo-kulcs stamp a leaf project-scope-ra (scope-prevenció, user-FR 2026-06-22) — a STABIL
+            // git/package identitás scope-szintű rögzítése; erre épül a repo-kulcs alapú duplikátum-detekció, ami
+            // a KÜLÖNBÖZŐ nevű, AZONOS repo eseteket (import vs scan) is elkapja. Best-effort (nincs kulcs → no-op).
+            // path-aware kulcs (2026-06-24 fix): a projekt-mappa neve diszkriminátorként → a monorepo/fork
+            // sub-projektek külön repoKey-t kapnak (nem keverednek egy scope-ba egy téves merge-dzsel).
+            const repoKey = fam_project_identity_util_1.FAM_ProjectIdentity_Util.canonicalRepoKey(identity, path.basename(set.discovery.resolvedRoot));
+            if (repoKey) {
+                await new scope_reference_2.FAM_Scope_DataService({ issuer: set.issuer }).setCanonicalRepoKey(leaf.scopeId, repoKey);
+            }
         }
         fsm_dynamo_1.DyFM_Log.info(`[famIngest] project-identity (${scopeLabel}): `
             + `${identity.packageName ?? '(nincs package.json)'}${identity.isGit ? ' [git]' : ''}`
@@ -693,7 +833,7 @@ class FAM_Ingest_ControlService {
             ingestRunId: set.runId, trigger: set.request.operation, table: [],
             scopePath: set.scopePath, rootPath: set.request.path,
             filesProcessed: 0, filesSkipped: 0, chunkCount: 0,
-            verdicts: { new: 0, modified: 0, equal: 0, deleted: 0 },
+            verdicts: { new: 0, modified: 0, equal: 0, deleted: 0, superseded: 0 },
             durationMs: Date.now() - set.startedAt, status: 'failed', errors: [errorEntry],
         };
         try {