@futdevpro/fdp-agent-memory 0.1.0 → 1.1.14

package/build/src/_collections/fam-reference-code.util.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ReferenceCode_Util = void 0;
+/**
+ * `FAM_ReferenceCode_Util` (FEAT-003) — azonosító-kód felismerő + normalizáló. **Pure** (dependency-
+ * mentes statikus util — FDP-konvenció: nincs top-level export-function). KÖZÖS choke-pont a write-
+ * (inverted-index építés) és a read- (determinisztikus expanzió) oldalon: az egyezés-garancia az, hogy
+ * MINDKÉT oldal UGYANEZT a felismerőt + normalizálást használja.
+ *
+ * Cél: requirement-/feature-/jegy-azonosító kódok (`REQ-AUTH-001`, `FEAT-001`, `BFR-AM-012`, `JIRA-1234`,
+ * `MP-5`, `SP-5.2`, `CVE-2021-1234`, …) kinyerése tetszőleges szövegből, normalizált (uppercase) alakban,
+ * dedup-olva. A vektor-keresés a kódokra gyenge (a parafrázisok zajba olvadnak) — a felismert kód EXPLICIT
+ * link-kulccsá válik (FEAT-003 §3). A FEAT-005 trigger-engine `regex`/`reference` triggerMode-ja is ezt használja.
+ */
+class FAM_ReferenceCode_Util {
+    /**
+     * A default felismerő-minta (generikus, magas-precízió — OSS-semleges, NEM hardkódol projekt-konvenciót).
+     * Nagybetűs prefix (≥2 kar) + 0+ `-<alnum>` szegmens + **numerikus farok** (`-<számjegyek>`, opc. `.<számjegyek>`):
+     * `REQ-AUTH-001` / `FEAT-001` / `ADR-004` / `BFR-AM-012` / `JIRA-1234` / `GH-123` / `MP-5` / `SP-5.2` /
+     * `FAM-REV-049` / `CVE-2021-1234`. A numerikus-farok kötöttség zárja ki a prózát; a `g`-flag a több-
+     * találatot. **Case-INSENSITIVE (`i`):** a kódok case-független azonosítók (`REQ-AUTH-001` ≡ `req-auth-001`)
+     * — a `normalize` uppercase-re hozza, hogy a write/read egyezzen. A precíziót a denylist őrzi (lent).
+     */
+    static DEFAULT_PATTERN = /\b[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)*-\d+(?:\.\d+)*\b/gi;
+    /**
+     * A FALSE-positive prefix-denylist (UPPERCASE-normalizált prefixre szűr — az ELSŐ `-` előtti szegmens):
+     * (a) kódolás-/szabvány-/termék-prefixek (`UTF-8`, `SHA-256`, `ISO-8601`, `AES-256`, `GPT-4`), (b) a
+     * case-insensitive matching miatt a gyakori lowercase-próza minták (`page-12`, `line-23`, `item-5`,
+     * `section-2`). Per-projekt felülírható (future config); a default konzervatív (a valódi REQ-/FEAT-/jegy-
+     * kódokat NEM érinti).
+     */
+    static PREFIX_DENYLIST = new Set([
+        // (a) kódolás / szabvány / termék
+        'UTF', 'UTF8', 'SHA', 'SHA1', 'SHA256', 'MD5', 'BASE', 'BASE64', 'ISO', 'AES', 'RSA',
+        'IPV', 'IPV4', 'IPV6', 'ES', 'ECMA', 'COVID', 'GPT', 'HTTP', 'TLS',
+        // (b) gyakori lowercase-próza (a case-insensitive matching zaj-csökkentése)
+        'PAGE', 'LINE', 'ITEM', 'STEP', 'FIG', 'NOTE', 'SECTION', 'CHAPTER', 'PART', 'ROW',
+        'COL', 'VOL', 'VER', 'VERSION', 'NUM', 'TABLE', 'APPENDIX',
+        // (c) Tailwind/CSS utility-prefixek (2026-06-20 audit false-positive: `bg-neutral-900`→BG, `py-1`→PY)
+        // — a `≥2`-karakteres prefixek (a minta `[A-Z][A-Z0-9]+` ≥2-t igényel; az 1-betűs `p-`/`m-`/`z-` nem match).
+        'BG', 'TEXT', 'PX', 'PY', 'PT', 'PB', 'PL', 'PR', 'MX', 'MY', 'MT', 'MB', 'ML', 'MR',
+        'GAP', 'SPACE', 'BORDER', 'RING', 'INSET', 'OPACITY', 'DIVIDE', 'LEADING', 'TRACKING',
+        'GRID', 'FLEX', 'ORDER', 'BASIS', 'GROW', 'SHRINK', 'TOP', 'BOTTOM', 'LEFT', 'RIGHT',
+        'MIN', 'MAX', 'ASPECT', 'SCALE', 'ROTATE', 'TRANSLATE', 'SKEW', 'DURATION', 'DELAY',
+        'INDENT', 'FILL', 'STROKE', 'OUTLINE', 'DECORATION',
+    ]);
+    /** Egy felismert kód max-hossza (pathológikus match elleni guard). */
+    static MAX_CODE_LENGTH = 64;
+    /** Egy szövegből kinyert kódok max-száma (DoS-guard nagy tartalomra). */
+    static MAX_CODES_PER_TEXT = 100;
+    /**
+     * Egy szöveg összes felismert kódja — **normalizált (uppercase), dedup-olt** listában (felismerés-sorrend).
+     * Üres / kód-mentes szöveg → üres tömb (a hívó ebből „nincs kód"-ot lát). Az `extraPatterns` opcionális
+     * per-projekt minták (a default MELLETT futnak); a denylist + normalizálás + dedup rájuk is alkalmazódik.
+     */
+    static extract(text, extraPatterns) {
+        if (typeof text !== 'string' || !text.length) {
+            return [];
+        }
+        const patterns = [FAM_ReferenceCode_Util.DEFAULT_PATTERN, ...(extraPatterns ?? [])];
+        const seen = new Set();
+        const result = [];
+        for (const pattern of patterns) {
+            // Friss lastIndex minden hívásnál (a `g`-flagű minta state-es; külön matchAll-lal izoláljuk).
+            const matches = text.matchAll(FAM_ReferenceCode_Util.global(pattern));
+            for (const match of matches) {
+                const candidate = FAM_ReferenceCode_Util.normalize(match[0]);
+                if (!FAM_ReferenceCode_Util.isAcceptable(candidate, seen)) {
+                    continue;
+                }
+                seen.add(candidate);
+                result.push(candidate);
+                if (result.length >= FAM_ReferenceCode_Util.MAX_CODES_PER_TEXT) {
+                    return result;
+                }
+            }
+        }
+        return result;
+    }
+    /** `true`, ha a szöveg TARTALMAZ legalább egy felismerhető kódot (a `read` gyors elágazásához). */
+    static containsCode(text, extraPatterns) {
+        return FAM_ReferenceCode_Util.extract(text, extraPatterns).length > 0;
+    }
+    /** Egy kód normalizálása (uppercase + trim) — a write/read egyezés-garanciájához (case-insensitive). */
+    static normalize(code) {
+        return code.trim().toUpperCase();
+    }
+    /**
+     * Egy jelölt elfogadható-e: nem üres, hossz-limit alatt, NEM denylist-prefix, és még nem láttuk.
+     * A prefix = az első `-` előtti szegmens (`BFR-AM-012` → `BFR`; `UTF-8` → `UTF`).
+     */
+    static isAcceptable(candidate, seen) {
+        if (!candidate.length || candidate.length > FAM_ReferenceCode_Util.MAX_CODE_LENGTH || seen.has(candidate)) {
+            return false;
+        }
+        const prefix = candidate.split('-', 1)[0];
+        return !FAM_ReferenceCode_Util.PREFIX_DENYLIST.has(prefix);
+    }
+    /** Egy minta `g`-flagű, friss-state másolata (a megosztott `g`-minta `lastIndex`-e ne szivárogjon). */
+    static global(pattern) {
+        const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
+        return new RegExp(pattern.source, flags);
+    }
+}
+exports.FAM_ReferenceCode_Util = FAM_ReferenceCode_Util;

package/build/src/_collections/fam-version.const.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_VERSION = void 0;
+const package_json_1 = require("../../package.json");
+/**
+ * A FAM package **futás-idejű verziója** — a `package.json`-ból (build-időben a `build/package.json`-ba
+ * másolva, a bootstrap is innen olvas). Egyetlen SSOT a verzió-riporthoz: a `/api/health` + a `/status`
+ * endpoint, és a `fam serve` boot-után-riport ezt adja vissza (a hardcode-olt `v0.0.1` helyett).
+ */
+exports.FAM_VERSION = package_json_1.version;

package/build/src/_models/data-models/fam-entry-base-properties.const.js

@@ -27,6 +27,7 @@ exports.famEntryBaseProperties = {
     embeddingStatus: { type: 'string', index: true, default: 'pending' },
     scopePath: { type: 'array', default: [] },
     referenceLinks: { type: 'string[]', default: [] },
+    referenceCodes: { type: 'string[]', index: true, default: [] },
     weight: { type: 'number', default: 1 },
     importance: { type: 'number', index: true },
     source: { type: 'object' },

package/build/src/_models/data-models/fam-entry.data-model.js

@@ -38,6 +38,12 @@ class FAM_Entry extends fsm_dynamo_1.DyFM_Metadata {
     scopePath = [];
     /** Feloldott reference-entitás `_id`-k (alias/fogalom kapcsolat — dsgn-002 §3). */
     referenceLinks = [];
+    /**
+     * A tartalomban felismert, normalizált azonosító-kódok (`REQ-AUTH-001`, `FEAT-001`, `BFR-AM-012`, …)
+     * — FEAT-003 inverted-index kulcs. A write-path (`embedAndPersist`) tölti a `FAM_ReferenceCode_Util`-lal;
+     * a read-path determinisztikus `find({ referenceCodes: $in })`-nel húzza be az ÖSSZES kódot citáló elemet.
+     */
+    referenceCodes = [];
     // --- pontozás ---
     /** Retrieval-score multiplikátor (`> 0`); `0` → kizárt. Default `1.0` (per-tár override). */
     weight = 1;

package/build/src/_models/data-models/fam-ingest-run.data-model.js

@@ -10,7 +10,9 @@ const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
  * `ingestRunId`-jét (`FAM_Entry.ingestRunId`) — így a run chunkjai csoportosan listázhatók/
  * törölhetők (dsgn-004 §5). MP-4 a fogyasztó/író; itt a stabil minimál szerződés.
  *
- * `_id` = a `runId` (UUID v4).
+ * `_id` = a `runId` — a Dynamo `saveData` által GENERÁLT Mongo ObjectId (stringként), a `FAM_Scope`
+ * mintáját követve. (A dsgn-004 §5 eredetileg UUID v4-et írt, de a Dynamo db-rétege `findById`-dal
+ * cast-olja a `_id`-t ObjectId-ra, így a client-generált UUID nem használható `_id`-ként.)
  */
 class FAM_IngestRun_DataModel extends fsm_dynamo_1.DyFM_Metadata {
     /** A futtatás triggere. */

package/build/src/_models/data-models/fam-reference.data-model.js

@@ -16,6 +16,12 @@ class FAM_Reference_DataModel extends fsm_dynamo_1.DyFM_Metadata {
     canonicalTerm;
     /** Aliasok: typo + fonetikus + STT variánsok, amelyek a canonical terminusra mutatnak. */
     aliasTerms = [];
+    /**
+     * NEGATÍV aliasok (disambiguáció — „ne keverjünk dolgokat"): azok a tokenek, amiket ez a reference EXPLICIT
+     * NEM old fel (veto). Ha a feloldandó token (normalizáltan) egyezik egy negatív-aliasszal, ez a reference
+     * KIESIK a kandidátusok közül (exact + fuzzy + vektor egyaránt) → nem keveredik egy hasonló nevű mással.
+     */
+    negativeAliases = [];
     /** Mit jelent / mire használt (a `canonicalTerm`-mel együtt adja a vektorizált tartalmat). */
     description;
     /** Vektorizált reprezentáció (canonicalTerm + description) — fuzzy match (embedding MP-2). */
@@ -52,6 +58,7 @@ exports.famReference_dataParams = new fsm_dynamo_1.DyFM_DataModel_Params({
     properties: {
         canonicalTerm: { type: 'string', index: true, required: true },
         aliasTerms: { type: 'string[]', index: true, default: [] },
+        negativeAliases: { type: 'string[]', index: true, default: [] },
         description: { type: 'string' },
         contentVector: {
             type: 'number[]', vectorizedFrom: ['canonicalTerm', 'description'],

package/build/src/_modules/capture/_collections/fam-capture.const.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_CAPTURE_DEFAULT_KIND = exports.FAM_DEFAULT_CAPTURE_SCOPE = void 0;
+/**
+ * FEAT-006 — az auto-capture default scope-ja, ha a hívó (hook) nem ad meg explicit scope-ot. A `write`
+ * KÖTELEZŐ scope-ot kíván; a hook-vezérelt capture ergonómiájához itt egy dedikált `session/agent-captures`
+ * home, ahova a kontextus-nélküli observation-ök esnek. A hívó felülírhatja (pl. projekt-scope-pal).
+ */
+exports.FAM_DEFAULT_CAPTURE_SCOPE = [{ layer: 'session', rawName: 'agent-captures' }];
+/** Az auto-capture default `kind`-ja (a `memory`-tár observation-jelölője). */
+exports.FAM_CAPTURE_DEFAULT_KIND = 'observation';

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

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_AutoCapture_ControlService = void 0;
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const embedding_1 = require("../../embedding");
+const ingest_1 = require("../../ingest");
+const fam_mcp_interface_1 = require("../../mcp/_models/interfaces/fam-mcp.interface");
+const fam_write_tool_service_1 = require("../../mcp/_services/fam-write-tool.service");
+const fam_capture_const_1 = require("../_collections/fam-capture.const");
+/**
+ * `FAM_AutoCapture_ControlService` (FEAT-006 1. réteg) — a hook-vezérelt **outbound session→`memory` auto-write**
+ * a claude-mem-paritás fő rése (a `write` kurált, explicit; ez nagy-frekvenciás, dedup-olt). Singleton.
+ *
+ * **Content-hash dedup (idempotencia):** a nagy-frekvenciás capture ELŐSZÖR ellenőrzi, van-e MÁR aktív
+ * `memory`-bejegyzés azonos kanonikus content-hash-sel (`FAM_ContentHash_Util`, a delta-detection SSOT-ja) —
+ * ha igen, **nem keletkezik duplikátum** (`captured:false`, `skipped:'duplicate'`). Egyébként a `write` create-
+ * úton ír (agent-provenance + auto-embed); a `contentHash`-t a create pillanatában explicit beírja (robusztus
+ * dedup akkor is, ha az embed később hibázna). A scope default-ol (`FAM_DEFAULT_CAPTURE_SCOPE`), ha a hook nem ad.
+ *
+ * **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_AutoCapture_ControlService {
+    static _instance;
+    issuer = 'FAM_AutoCapture_ControlService';
+    static getInstance() {
+        if (!FAM_AutoCapture_ControlService._instance) {
+            FAM_AutoCapture_ControlService._instance = new FAM_AutoCapture_ControlService();
+        }
+        return FAM_AutoCapture_ControlService._instance;
+    }
+    /**
+     * Egy session-observation auto-capture-je a `memory`-tárba. Content-hash dedup → ha új, `write` create
+     * (agent-provenance + auto-embed). Üres `content` → leíró validációs hiba (dsgn-008, nem néma).
+     */
+    async capture(input) {
+        const content = (input?.content ?? '').trim();
+        if (!content) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteMissingField,
+                message: 'Az `auto_capture` `content`-et igényel (a megfigyelés vektorizálandó szövege).',
+                issuer: this.issuer,
+                context: { operation: 'auto-capture' },
+            });
+        }
+        const contentHash = ingest_1.FAM_ContentHash_Util.hash(content);
+        // Dedup: van-e MÁR aktív memory-bejegyzés azonos content-hash-sel? → idempotens skip (nincs duplikátum).
+        const existing = await this.findByHash(contentHash);
+        if (existing && existing._id) {
+            return { captured: false, skipped: 'duplicate', id: existing._id, contentHash: contentHash };
+        }
+        // Új capture → a `write` create-úton (agent-provenance, auto-embed). A `source.path` a sessionId
+        // provenance-jelölő (a `fields.source` felülírja a write default `{type:'agent'}`-ját).
+        const writeInput = {
+            table: fam_table_type_enum_1.FAM_Table.memory,
+            operation: fam_mcp_interface_1.FAM_WriteOperation.create,
+            content: content,
+            scopePath: (input.scopePath && input.scopePath.length) ? input.scopePath : fam_capture_const_1.FAM_DEFAULT_CAPTURE_SCOPE,
+            tags: input.tags,
+            kind: input.kind ?? fam_capture_const_1.FAM_CAPTURE_DEFAULT_KIND,
+            fields: input.sessionId
+                ? { contentHash: contentHash, source: { type: 'agent', path: input.sessionId } }
+                : { contentHash: contentHash },
+        };
+        const output = await fam_write_tool_service_1.FAM_WriteTool_Service.getInstance().handle(writeInput);
+        return {
+            captured: true,
+            id: output.created[0] ?? null,
+            contentHash: contentHash,
+            warnings: output.warnings.length ? output.warnings : undefined,
+        };
+    }
+    /** Az első aktív `memory`-bejegyzés az adott content-hash-sel (a dedup kulcsa) — vagy `null`, ha nincs. */
+    async findByHash(contentHash) {
+        const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(fam_table_type_enum_1.FAM_Table.memory);
+        if (!registryEntry) {
+            return null;
+        }
+        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const filter = { contentHash: contentHash };
+        const matches = await dataService.findDataList(filter);
+        return matches.length ? matches[0] : null;
+    }
+}
+exports.FAM_AutoCapture_ControlService = FAM_AutoCapture_ControlService;

package/build/src/_modules/capture/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_CAPTURE_DEFAULT_KIND = exports.FAM_DEFAULT_CAPTURE_SCOPE = exports.FAM_AutoCapture_ControlService = void 0;
+var fam_auto_capture_control_service_1 = require("./_services/fam-auto-capture.control-service");
+Object.defineProperty(exports, "FAM_AutoCapture_ControlService", { enumerable: true, get: function () { return fam_auto_capture_control_service_1.FAM_AutoCapture_ControlService; } });
+var fam_capture_const_1 = require("./_collections/fam-capture.const");
+Object.defineProperty(exports, "FAM_DEFAULT_CAPTURE_SCOPE", { enumerable: true, get: function () { return fam_capture_const_1.FAM_DEFAULT_CAPTURE_SCOPE; } });
+Object.defineProperty(exports, "FAM_CAPTURE_DEFAULT_KIND", { enumerable: true, get: function () { return fam_capture_const_1.FAM_CAPTURE_DEFAULT_KIND; } });

package/build/src/_modules/embedding/_collections/fam-embedding-prefix.util.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_EmbeddingPrefix_Util = void 0;
+/**
+ * `FAM_EmbeddingPrefix_Util` (FEAT-004) — **task-prefix + query/document aszimmetria** (pure, állapot-
+ * mentes). A live-keresés-teszt (2026-06-20) bizonyította: a FAM a NYERS szöveget embeddeli, de a
+ * `nomic-embed-text-v1.5` (és sok instruction-tuned modell) `search_query:` / `search_document:` prefixet
+ * VÁR — enélkül magas a zaj-padló (~0.5–0.63 a nem-kapcsolódóknál is) + gyenge a szeparáció. A
+ * `FAM_EmbedCallType` MÁR megkülönbözteti a query-t (`embed-query`) a doc-tól (`embed-write`/`-scan`/
+ * `-re-embed`) → per-modell, per-irány prefix sokat javít a találat-szeparáción.
+ *
+ * **Konzisztencia-szerződés:** a write ÉS a read UGYANAZT a sémát alkalmazza (doc-prefix mentéskor,
+ * query-prefix kereséskor). Ha egy meglévő korpusz prefix NÉLKÜL készült, a séma BEKAPCSOLÁSA `re-embed`-et
+ * igényel (a doc-oldal újraírásához); egy friss korpusz eleve konzisztens.
+ *
+ * **Mock-provider:** a hívó (`FAM_Embedding_ControlService`) `mock` providernél `off`-ot ad — a mock
+ * determinisztikus hash, az aszimmetrikus prefix elrontaná a query↔doc egyezést (a teszt-double match-ét).
+ */
+class FAM_EmbeddingPrefix_Util {
+    /** A nomic-embed (és OpenAI-kompatibilis instruction-tuned) család sémája. */
+    static NOMIC_SCHEME = {
+        queryPrefix: 'search_query: ',
+        documentPrefix: 'search_document: ',
+    };
+    /** Modell-név-minta → séma. Bővíthető (új instruction-tuned modell-családokra). */
+    static CATALOG = [
+        { pattern: /nomic-embed/i, scheme: FAM_EmbeddingPrefix_Util.NOMIC_SCHEME },
+    ];
+    /** `true`, ha a hívás a QUERY-oldal (read-vektor); minden más callType document-oldal (write/scan/re-embed). */
+    static isQuery(callType) {
+        return callType === 'embed-query';
+    }
+    /** A modellhez tartozó prefix-séma (név-match a katalógusból), vagy `null` ha nincs ismert séma. */
+    static resolveScheme(modelId) {
+        if (typeof modelId !== 'string' || !modelId.length) {
+            return null;
+        }
+        for (const entry of FAM_EmbeddingPrefix_Util.CATALOG) {
+            if (entry.pattern.test(modelId)) {
+                return entry.scheme;
+            }
+        }
+        return null;
+    }
+    /**
+     * A konkrét prefix-string egy modellhez + callType-hoz + mode-hoz. `off` → `''`; `auto` → a név-matchelt
+     * séma iránya (vagy `''` ha a modell nem ismert prefix-igényűnek); `on` → a matchelt séma VAGY (ha nincs
+     * match) a nomic-default — erőltetve. A `''` prefix = nincs változtatás.
+     */
+    static resolvePrefix(set) {
+        if (set.mode === 'off') {
+            return '';
+        }
+        let scheme = FAM_EmbeddingPrefix_Util.resolveScheme(set.modelId);
+        if (set.mode === 'on' && !scheme) {
+            scheme = FAM_EmbeddingPrefix_Util.NOMIC_SCHEME;
+        }
+        if (!scheme) {
+            return '';
+        }
+        return FAM_EmbeddingPrefix_Util.isQuery(set.callType) ? scheme.queryPrefix : scheme.documentPrefix;
+    }
+    /**
+     * A prefix alkalmazása MINDEN szövegre (a `texts` sorrendjét megtartva). Üres prefix → a bemeneti
+     * tömb VÁLTOZATLANUL (zero-overhead a prefix-mentes esetre — pl. openai/mock/off).
+     */
+    static apply(set) {
+        const prefix = FAM_EmbeddingPrefix_Util.resolvePrefix({
+            modelId: set.modelId, callType: set.callType, mode: set.mode,
+        });
+        if (!prefix) {
+            return set.texts;
+        }
+        return set.texts.map((text) => `${prefix}${text}`);
+    }
+}
+exports.FAM_EmbeddingPrefix_Util = FAM_EmbeddingPrefix_Util;

package/build/src/_modules/embedding/_services/fam-duplicate-scan.control-service.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_DuplicateScan_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const fam_store_registry_const_1 = require("../_collections/fam-store-registry.const");
+const fam_entry_data_service_1 = require("./fam-entry.data-service");
+const fam_vector_search_control_service_1 = require("./fam-vector-search.control-service");
+/**
+ * `FAM_DuplicateScan_ControlService` — **near-duplikátum / multiplikáció FELDERÍTŐ eszköz** (user-direktíva
+ * 2026-06-21). Egy tár vektor-pool-jában megkeresi a NAGYON HASONLÓ (koszinusz ≥ `threshold`) entry-ket, és
+ * **cluster-ekbe** vonja őket (union-find a hasonlóság-éleken). **NEM töröl** — csak megmutatja az
+ * ismétlődéseket (dokumentumokban és memóriákban is várható), hogy a user felismerhesse a mintákat és DÖNTSÖN.
+ *
+ * **Algoritmus + korlátok:** minden (capolt) entry-re a pool top-`neighbors` koszinusz-szomszédja → a küszöb
+ * feletti párok élek → union-find → komponensek (méret ≥ 2 = duplikátum-cluster). A `maxEntries` cap védi az
+ * O(n²)-blowup-tól (a `capped` flag JELZI, ha nem a teljes tárat néztük — nincs néma csonkolás). Read-only.
+ */
+class FAM_DuplicateScan_ControlService {
+    static _instance;
+    issuer = 'FAM_DuplicateScan_ControlService';
+    /** Default koszinusz-küszöb: 0.95 (e felett „nagyon hasonló"). Hangolható a `threshold` inputtal. */
+    static DEFAULT_THRESHOLD = 0.95;
+    /** Default szomszéd-szám entry-nként (a top-K a duplikátum-élekhez). */
+    static DEFAULT_NEIGHBORS = 10;
+    /** Default entry-cap (az O(n²) elleni védelem; a `capped` jelzi, ha a tár nagyobb). */
+    static DEFAULT_MAX_ENTRIES = 3000;
+    /** Default output-cluster-cap (a legnagyobb cluster-ek elöl). */
+    static DEFAULT_MAX_CLUSTERS = 100;
+    /** A riport-snippet max hossza. */
+    static SNIPPET_LENGTH = 140;
+    static getInstance() {
+        if (!FAM_DuplicateScan_ControlService._instance) {
+            FAM_DuplicateScan_ControlService._instance = new FAM_DuplicateScan_ControlService();
+        }
+        return FAM_DuplicateScan_ControlService._instance;
+    }
+    /** Egy tár near-duplikátum scan-je (read-only). Üres pool → üres eredmény (nem dob). */
+    async scan(input) {
+        const threshold = input.threshold ?? FAM_DuplicateScan_ControlService.DEFAULT_THRESHOLD;
+        const neighbors = input.neighbors ?? FAM_DuplicateScan_ControlService.DEFAULT_NEIGHBORS;
+        const maxEntries = input.maxEntries ?? FAM_DuplicateScan_ControlService.DEFAULT_MAX_ENTRIES;
+        const maxClusters = input.maxClusters ?? FAM_DuplicateScan_ControlService.DEFAULT_MAX_CLUSTERS;
+        const registryEntry = fam_store_registry_const_1.FAM_StoreRegistry_Util.getEntry(input.table);
+        const search = fam_vector_search_control_service_1.FAM_VectorSearch_ControlService.getInstance();
+        const totalInPool = registryEntry ? search.getPoolSize(input.table) : 0;
+        const empty = {
+            table: input.table, threshold: threshold, totalInPool: totalInPool, scanned: 0,
+            capped: false, clusterCount: 0, duplicateEntryCount: 0, clusters: [],
+        };
+        if (!registryEntry || !totalInPool) {
+            return empty;
+        }
+        // 1. A (capolt) (id, vektor) halmaz lean-streamelése (NEM a teljes content — csak a vektorok).
+        const dataService = new fam_entry_data_service_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const ids = [];
+        const vectors = [];
+        const filter = { embeddingStatus: 'completed' };
+        await dataService.streamHydratableVectors(filter, (id, contentVector) => {
+            if (ids.length < maxEntries) {
+                ids.push(id);
+                vectors.push(contentVector);
+            }
+        });
+        const scanned = ids.length;
+        const capped = totalInPool > scanned;
+        // 2. Élek: minden entry top-szomszédai a küszöb felett (a saját maga kizárva). Per-entry try/catch
+        // (egy dimenzió-/embedding-anomália NE döntse az egész scan-t).
+        const edges = [];
+        for (let i = 0; i < scanned; i++) {
+            try {
+                const hits = await search.search({ table: input.table, queryVector: vectors[i], topK: neighbors + 1 });
+                for (const hit of hits) {
+                    if (hit.id !== ids[i] && hit.score >= threshold) {
+                        edges.push({ a: ids[i], b: hit.id, score: hit.score });
+                    }
+                }
+            }
+            catch (error) {
+                fsm_dynamo_1.DyFM_Log.warn(`[FAM dup-scan] '${input.table}' entry '${ids[i]}' keresése kihagyva: ${error?.message}`);
+            }
+        }
+        // 3. Union-find → komponensek (méret ≥ 2 = duplikátum-cluster). Tiszta.
+        const components = FAM_DuplicateScan_ControlService.clusterFromEdges(edges);
+        // 4. Snippet-ek CSAK a clustered id-kre (kis halmaz; a felismeréshez).
+        const clusteredIds = new Set();
+        for (const component of components) {
+            for (const id of component.ids) {
+                clusteredIds.add(id);
+            }
+        }
+        const metaById = await this.fetchMeta(dataService, clusteredIds);
+        // 5. Cluster-ek építése + rendezés (legnagyobb/legtömörebb elöl) + output-cap.
+        const clusters = components
+            .map((component) => ({
+            size: component.ids.length,
+            maxScore: component.maxScore,
+            minScore: component.minScore,
+            members: component.ids.map((id) => ({
+                id: id,
+                kind: metaById.get(id)?.kind,
+                snippet: metaById.get(id)?.snippet,
+            })),
+        }))
+            .sort((left, right) => right.size - left.size || right.maxScore - left.maxScore);
+        const duplicateEntryCount = clusters.reduce((sum, cluster) => sum + cluster.size, 0);
+        return {
+            table: input.table,
+            threshold: threshold,
+            totalInPool: totalInPool,
+            scanned: scanned,
+            capped: capped,
+            clusterCount: clusters.length,
+            duplicateEntryCount: duplicateEntryCount,
+            clusters: clusters.slice(0, maxClusters),
+        };
+    }
+    /**
+     * **Tiszta union-find**: a hasonlóság-élekből összefüggő komponensek (méret ≥ 2). Minden komponens id-i
+     * rendezve + a komponens score-tartománya (min/max él-score). Determinista (azonos input → azonos output).
+     * Side-effect-mentes → unit-tesztelhető a pool/DB nélkül.
+     */
+    static clusterFromEdges(edges) {
+        const parent = new Map();
+        const ensure = (node) => {
+            if (!parent.has(node)) {
+                parent.set(node, node);
+            }
+        };
+        const find = (node) => {
+            let root = node;
+            while (parent.get(root) !== root) {
+                root = parent.get(root);
+            }
+            // path-compression
+            let cursor = node;
+            while (parent.get(cursor) !== root) {
+                const next = parent.get(cursor);
+                parent.set(cursor, root);
+                cursor = next;
+            }
+            return root;
+        };
+        for (const edge of edges) {
+            ensure(edge.a);
+            ensure(edge.b);
+            const rootA = find(edge.a);
+            const rootB = find(edge.b);
+            if (rootA !== rootB) {
+                parent.set(rootA, rootB);
+            }
+        }
+        const idsByRoot = new Map();
+        for (const node of parent.keys()) {
+            const root = find(node);
+            const bucket = idsByRoot.get(root);
+            if (bucket) {
+                bucket.add(node);
+            }
+            else {
+                idsByRoot.set(root, new Set([node]));
+            }
+        }
+        const scoreByRoot = new Map();
+        for (const edge of edges) {
+            const root = find(edge.a);
+            const current = scoreByRoot.get(root) ?? { min: Number.POSITIVE_INFINITY, max: Number.NEGATIVE_INFINITY };
+            current.min = Math.min(current.min, edge.score);
+            current.max = Math.max(current.max, edge.score);
+            scoreByRoot.set(root, current);
+        }
+        const result = [];
+        for (const [root, ids] of idsByRoot) {
+            if (ids.size < 2) {
+                continue;
+            }
+            const score = scoreByRoot.get(root) ?? { min: 0, max: 0 };
+            result.push({ ids: [...ids].sort(), maxScore: score.max, minScore: score.min });
+        }
+        return result;
+    }
+    /** A clustered id-k jelleg + snippet metaadata (egy lean lekérdezés, csak a kis clustered halmazra). */
+    async fetchMeta(dataService, clusteredIds) {
+        const metaById = new Map();
+        if (!clusteredIds.size) {
+            return metaById;
+        }
+        const entries = await dataService.findHydratableList({ _id: { $in: [...clusteredIds] } });
+        for (const entry of entries) {
+            const id = String(entry._id ?? '');
+            if (!id) {
+                continue;
+            }
+            const content = typeof entry.content === 'string' ? entry.content : '';
+            metaById.set(id, {
+                kind: entry.kind,
+                snippet: content.replace(/\s+/g, ' ').trim().slice(0, FAM_DuplicateScan_ControlService.SNIPPET_LENGTH),
+            });
+        }
+        return metaById;
+    }
+}
+exports.FAM_DuplicateScan_ControlService = FAM_DuplicateScan_ControlService;

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

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_EmbeddingPipeline_ControlService = void 0;
-const tslib_1 = require("tslib");
-const crypto = tslib_1.__importStar(require("crypto"));
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_reference_code_util_1 = require("../../../_collections/fam-reference-code.util");
 const errors_control_service_1 = require("../../../_routes/server/errors/errors.control-service");
 const fam_store_registry_const_1 = require("../_collections/fam-store-registry.const");
+const fam_content_hash_util_1 = require("../../ingest/_collections/fam-content-hash.util");
 const fam_embedding_control_service_1 = require("./fam-embedding.control-service");
 const fam_entry_data_service_1 = require("./fam-entry.data-service");
 const fam_vector_search_control_service_1 = require("./fam-vector-search.control-service");
@@ -55,8 +55,15 @@ class FAM_EmbeddingPipeline_ControlService {
             return { status: 'error', dims: 0 };
         }
         const dataService = new fam_entry_data_service_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        // FEAT-003: a tartalomban felismert azonosító-kódok inverted-index-be írása — az embed-sikertől
+        // FÜGGETLENÜL (az embed-try ELŐTT), hogy a kód-citáció a még nem embeddelt / embed-bukott elemen is
+        // megjelenjen a determinisztikus read-expanzióban. A re-embed (teljes tár) így BACKFILL-eli a régieket.
+        await this.persistReferenceCodes(set.entry, dataService);
         const composed = this.composeVectorizedText(set.entry, registryEntry.vectorizedFrom);
-        const contentHash = this.sha256(composed);
+        // A `contentHash` a KANONIKUS content-hash (`FAM_ContentHash_Util`, a delta-detection SSOT-ja) — NEM
+        // a `composed` vektor-szöveg hash-e. Korábban az utóbbit írtuk a `contentHash` mezőbe, amit a delta
+        // a `chunk.content` hash-éhez hasonlít → SOHA nem egyezett → minden re-scan `modified` (fölös re-embed).
+        const contentHash = fam_content_hash_util_1.FAM_ContentHash_Util.hash(typeof set.entry.content === 'string' ? set.entry.content : '');
         if (!composed.trim().length) {
             // Nincs vektorizálható content → marad pending (a write-validáció a content-kötelezőséget
             // külön kezeli; itt csak jelezzük, hogy nincs mit embeddelni).
@@ -181,13 +188,30 @@ class FAM_EmbeddingPipeline_ControlService {
         }
         return parts.join('\n');
     }
-    /** SHA-256(normalizált szöveg) — a delta-detection contentHash-e (dsgn-001 / dsgn-004 §4). */
-    sha256(text) {
-        return crypto.createHash('sha256').update(this.normalize(text)).digest('hex');
+    /**
+     * FEAT-003 — a `content`-ből felismert azonosító-kódok `referenceCodes`-ba írása (`FAM_ReferenceCode_Util`).
+     * **Changed-only:** ha a felismert halmaz megegyezik a már perzistálttal → NINCS `$set` (a teljes-tár
+     * re-embed N entry-jén a fölös write elkerülése). Az in-memory `entry.referenceCodes`-t is frissíti (a
+     * hívó esetleges azonnali olvasásához). DB-`_id` nélkül no-op.
+     */
+    async persistReferenceCodes(entry, dataService) {
+        if (!entry._id) {
+            return;
+        }
+        const codes = fam_reference_code_util_1.FAM_ReferenceCode_Util.extract(typeof entry.content === 'string' ? entry.content : '');
+        if (this.sameCodeSet(codes, entry.referenceCodes ?? [])) {
+            return;
+        }
+        entry.referenceCodes = codes;
+        await dataService.setReferenceCodes(entry._id, codes);
     }
-    /** Egyszerű normalizálás a hash-hez (whitespace-tömörítés + trim) — a delta-konzisztenciához. */
-    normalize(text) {
-        return text.replace(/\s+/g, ' ').trim();
+    /** Két kód-halmaz egyezése (sorrend-független) — a changed-only `$set`-kapuhoz. */
+    sameCodeSet(a, b) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        const setB = new Set(b);
+        return a.every((code) => setB.has(code));
     }
     /** A scope-szűkítő filter (a `scopePath` LEVÉL scopeId-jára). Üres scope → teljes tár (`!_deleted`). */
     buildScopeFilter(scopePath) {