@futdevpro/fdp-agent-memory 0.1.0 → 1.1.14

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

@@ -115,7 +115,11 @@ class FAM_ScopeResolver_ControlService {
     async fuzzyResolve(rawToken, context) {
         const reference_DS = new fam_reference_data_service_1.FAM_Reference_DataService({ issuer: this.issuer });
         const allReferences = await this.getActiveReferences();
-        const references = reference_DS.filterByContext(allReferences, context);
+        // Negatív-alias veto (disambiguáció): a tokent EXPLICIT disclaim-elő reference-eket kiszűrjük MÁR a matching
+        // ELŐTT (exact + string-fuzzy + vektor egyaránt) → nem keveredik egy hasonló nevű, de más fogalommal.
+        const normalizedToken = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(rawToken);
+        const references = reference_DS.filterByContext(allReferences, context)
+            .filter((reference) => !fam_reference_data_service_1.FAM_Reference_DataService.vetoesToken(normalizedToken, reference));
         const candidates = [];
         // (1) Exact fast-path (score 1.0).
         const exact = reference_DS.exactMatch(rawToken, references);
@@ -142,6 +146,12 @@ class FAM_ScopeResolver_ControlService {
      * A token embeddelése a vektor-fuzzy-hoz (MP-2 `FAM_Embedding_ControlService`). Bármilyen hiba /
      * üres pool / nincs provider → üres vektor + `warn` (graceful degrade — a string-fuzzy ág teljes
      * értékű marad MP-2 nélkül; dsgn-002 §3.1 SP-3.2 kockázat). NEM dob, NEM néma (warn-log).
+     *
+     * **FEAT-004 figyelem (F4-2):** a `callType: 'embed-query'` itt SZÁNDÉKOS — az alias-match query↔query
+     * hasonlóság (token vs canonicalTerm), NEM query↔document. Ha valaha bekötöd a reference DOC-ok
+     * (`FAM_Reference.contentVector`) embeddelését, az is `'embed-query'`-vel menjen (azonos task-prefix-
+     * séma), KÜLÖNBEN a FEAT-004 query/document aszimmetria (`search_query:` vs `search_document:`)
+     * elrontaná a cosine-egyezést. (Jelenleg a reference doc-vektor SEHOL nem készül → a vektor-fuzzy dormant.)
      */
     async embedTokenSafe(rawToken) {
         try {
@@ -220,22 +230,27 @@ class FAM_ScopeResolver_ControlService {
         let parentScopeId = undefined;
         for (const rawLayer of rawScopePath) {
             const candidates = await this.fuzzyResolve(rawLayer.rawName, { scopeLayer: rawLayer.layer });
-            const classification = this.classifyResolution(candidates, minScore);
-            if (classification === 'ambiguous-multi') {
-                throw this.ambiguousError(rawLayer, candidates, minScore);
+            // FAM-REV-059: a write-resolve KONZERVATÍV — csak EXACT reference-match (a rawName pontos alias/canonical)
+            // redirect-elhet egy meglévő (akár MÁS nevű) scope-ra; a FUZZY match (string/vektor) NEM, különben a
+            // hasonló nevű TESTVÉR-package-ek keresztbe-scope-olódnak ("ngx-dynamo" ~80% ~ "nts-dynamo" → az ngx az
+            // nts scope-ba kerülne). Ambiguus CSAK több KÜLÖNBÖZŐ EXACT match esetén (két scope ugyanazt a pontos
+            // aliast állítja); a fuzzy-ambiguitás NEM blokkol — a write a RAW nevet használja (a near-match note-olva).
+            const exacts = candidates.filter((candidate) => candidate.matchSource === 'exact');
+            if (exacts.length > 1) {
+                throw this.ambiguousError(rawLayer, exacts, minScore);
             }
             const resolved = await this.resolveOneWriteLayer({
                 rawLayer: rawLayer,
-                candidates: candidates,
-                classification: classification,
+                exactCandidate: exacts[0],
                 parentScopeId: parentScopeId,
                 autoCreate: autoCreate,
                 scopeDataService: scope_DS,
             });
             layers.push(resolved);
             parentScopeId = resolved.scopeRef.scopeId;
-            // Van-match-bizonytalan: confident, de fuzzy (NEM exact) volt → uncertaintyNote (NEM hiba).
-            if (classification === 'confident' && candidates.length && candidates[0].matchSource !== 'exact') {
+            // Nincs exact, de van confident fuzzy near-match → uncertaintyNote (a write a RAW nevet használta — a
+            // hívó lássa, hogy volt hasonló nevű scope; NEM hiba, NEM néma redirect — FAM-REV-059).
+            if (!exacts.length && candidates.length && this.classifyResolution(candidates, minScore) !== 'no-match') {
                 uncertaintyNotes.push(this.toUncertaintyNote(rawLayer.rawName, candidates));
             }
         }
@@ -246,27 +261,26 @@ class FAM_ScopeResolver_ControlService {
         };
     }
     /**
-     * Egy write-layer feloldása (a `resolveForWrite` belső lépése). `confident` + scope-match → a
-     * meglévő scope; egyébként (confident-de-csak-fogalmi-alias VAGY no-match) → auto-regiszt
-     * (ha `autoCreate`), KÜLÖNBEN `FAM-REF-RESOLVE-001` (nincs match + nincs auto-create).
+     * Egy write-layer feloldása (a `resolveForWrite` belső lépése, FAM-REV-059). Az `exactCandidate` az EGYETLEN
+     * EXACT reference-match (a rawName pontos aliasa/canonical-ja), vagy `undefined`. (a) ha scope-entitásra mutat
+     * → annak scopeId-ja; (b) ha csak fogalmi alias → a canonical néven find-or-create; (c) ha NINCS exact (fuzzy/
+     * no-match) → a NYERS néven find-or-create (a fuzzy NEM redirect-el a hasonló testvér-névre). Auto-regiszt csak
+     * ha `autoCreate`, KÜLÖNBEN `FAM-REF-RESOLVE-001`.
      */
     async resolveOneWriteLayer(set) {
-        // (a) confident reference-match, ami EGY konkrét scope-entitásra mutat → annak a scopeId-ja.
-        if (set.classification === 'confident' && set.candidates.length && set.candidates[0].canonicalScopeRef?.scopeId) {
-            const ref = set.candidates[0].canonicalScopeRef;
-            return { scopeRef: ref, created: false };
+        // (a) EXACT reference-match, ami EGY konkrét scope-entitásra mutat → annak a scopeId-ja.
+        if (set.exactCandidate?.canonicalScopeRef?.scopeId) {
+            return { scopeRef: set.exactCandidate.canonicalScopeRef, created: false };
         }
-        // (b) confident, de csak fogalmi alias (nincs scope-ref): a canonical néven find-or-create.
-        // (c) no-match: a nyers néven find-or-create — DE csak ha autoCreate; egyébként hiba.
-        const isConfident = set.classification === 'confident' && set.candidates.length > 0;
-        const canonicalName = isConfident ? set.candidates[0].canonicalTerm : set.rawLayer.rawName;
+        // (b) EXACT, de csak fogalmi alias (nincs scope-ref): a canonical néven. (c) NINCS exact: a NYERS néven.
+        const canonicalName = set.exactCandidate ? set.exactCandidate.canonicalTerm : set.rawLayer.rawName;
         // Determinisztikus de-dup: a (normalizált név + layer + parent) hármasra már létezik-e?
         const existing = await set.scopeDataService.findByCanonical(set.rawLayer.layer, canonicalName, set.parentScopeId);
         if (existing.length && existing[0]._id) {
             return { scopeRef: this.toScopeRef(existing[0]), created: false };
         }
         if (!set.autoCreate) {
-            throw this.noMatchError(set.rawLayer, set.candidates, await this.resolveFuzzyMinScore());
+            throw this.noMatchError(set.rawLayer, set.exactCandidate ? [set.exactCandidate] : [], await this.resolveFuzzyMinScore());
         }
         // Auto-regiszt (createdBy='agent-write', parent = az előző layer scopeId-ja).
         const created = await set.scopeDataService.findOrCreateScope({
@@ -322,6 +336,15 @@ class FAM_ScopeResolver_ControlService {
      */
     async resolveReadLayerScopeIds(set) {
         if (set.classification === 'no-match') {
+            // Reference-index MISS → fallback a scope-ENTITÁSOKRA (a write-path `findByCanonical`-jával
+            // szimmetrikusan, dsgn-002 §3.2). A `scan` a scope-entitást létrehozza, de `fam_reference`
+            // alias-bejegyzést NEM — enélkül a read-filter SOHA nem oldódna fel (FAM-REF-RESOLVE-001),
+            // pedig a scope a fán LÉTEZIK. Ha van canonical-név-match erre a layerre → annak a subtree-ja;
+            // csak ha ez is üres → a feloldhatatlan-filter hiba (nincs csendes üres-prefilter).
+            const entityScopeIds = await this.entityFallbackScopeIds(set.rawLayer, set.scopeDataService);
+            if (entityScopeIds.length) {
+                return entityScopeIds;
+            }
             throw this.noMatchError(set.rawLayer, set.candidates, set.minScore);
         }
         // A confident (top-1) + az ambiguous-multi (a >= minScore közeli kandidátusok) scope-jai.
@@ -343,6 +366,23 @@ class FAM_ScopeResolver_ControlService {
         }
         return result;
     }
+    /**
+     * Read-filter fallback (a `no-match` ág): egy raw-layer canonical-nevének EXACT match-e a
+     * scope-ENTITÁSOK fáján (a reference-indexet megkerülve), majd a match(ek) `getSubtreeScopeIds`
+     * uniója. A `scan` scope-entitást ír, de `fam_reference` alias-t NEM — ez teszi a read-filtert
+     * feloldhatóvá reference-bejegyzés nélkül is. Üres lista = nincs entitás-match.
+     */
+    async entityFallbackScopeIds(rawLayer, scopeDataService) {
+        const matches = await scopeDataService.findByCanonical(rawLayer.layer, rawLayer.rawName);
+        const result = [];
+        for (const scope of matches) {
+            if (scope._id) {
+                const subtree = await scopeDataService.getSubtreeScopeIds(scope._id);
+                result.push(...subtree);
+            }
+        }
+        return result;
+    }
     /**
      * Egy kandidátus → a fán létező scopeId (read-expand). Ha a kandidátus konkrét scope-ref-et hordoz
      * → annak az scopeId-ja; egyébként a canonical néven keresünk a layerben (a read NEM hoz létre
@@ -382,12 +422,17 @@ class FAM_ScopeResolver_ControlService {
     async traceResolution(rawTokens, mode) {
         const minScore = await this.resolveFuzzyMinScore();
         const queryVectorAvailable = (await this.embedTokenSafe(rawTokens[0]?.rawName ?? '')).length > 0;
+        const scope_DS = new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer });
         const steps = [];
         for (const rawLayer of rawTokens) {
             const context = mode === 'query-expand' ? undefined : { scopeLayer: rawLayer.layer };
             const candidates = await this.fuzzyResolve(rawLayer.rawName, context);
             const classification = this.classifyResolution(candidates, minScore);
             const decided = classification === 'confident' ? candidates[0] : undefined;
+            // FAM-REV-041: a reference-réteg után az entity-fallback (scope-entitás canonical-match) is a
+            // trace-be — ez oldja fel a valós write/read scope-ot üres reference-indexnél is (nincs hamis
+            // no-match egy létező scope-ra). Query-expand módban (nincs layer) kihagyjuk.
+            const entityFallback = mode === 'query-expand' ? undefined : await this.traceEntityFallback(rawLayer, scope_DS);
             steps.push({
                 rawToken: rawLayer.rawName,
                 normalizedForm: fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(rawLayer.rawName),
@@ -396,6 +441,7 @@ class FAM_ScopeResolver_ControlService {
                 classification: classification,
                 decidedMatchSource: decided?.matchSource,
                 decidedCanonical: decided?.canonicalTerm,
+                entityFallback: entityFallback,
             });
         }
         const cacheAge = this.referenceCache ? Date.now() - this.referenceCache.loadedAt : 0;
@@ -406,6 +452,19 @@ class FAM_ScopeResolver_ControlService {
             referenceCacheAgeMs: cacheAge,
         };
     }
+    /**
+     * Egy raw-layer entity-fallback trace-e (FAM-REV-041): a scope-ENTITÁSOK fáján canonical-név-match
+     * (`findByCanonical` — ugyanaz a kulcs, amit a write `resolveOneWriteLayer` és a read
+     * `entityFallbackScopeIds` használ). NEM mutál (nem hoz létre scope-ot) — csak diagnosztika.
+     */
+    async traceEntityFallback(rawLayer, scopeDataService) {
+        const matches = await scopeDataService.findByCanonical(rawLayer.layer, rawLayer.rawName);
+        const hit = matches.find((scope) => !!scope._id);
+        if (hit && hit._id) {
+            return { matched: true, scopeId: hit._id, canonicalName: hit.canonicalName };
+        }
+        return { matched: false };
+    }
     // =========================================================================
     // UNCERTAINTY + hiba-építés (dsgn-002 §4, SP-3.4)
     // =========================================================================

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Api_Controller = void 0;
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const fam_version_const_1 = require("../../../_collections/fam-version.const");
 const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
 const fam_config_level_type_enum_1 = require("../../../_enums/fam-config-level.type-enum");
 const config_control_service_1 = require("../config/config.control-service");
@@ -22,7 +23,7 @@ const MAIN_TABLES = [
  * belépési pontja: a 3 core-tool **REST-tükre** + a UI-specifikus listázó/stat/ingest endpoint-ok.
  * A REST-handler UGYANAZT a transport-agnosztikus core-service-t hívja, mint az MCP-réteg
  * (`FAM_ReadTool_Service`/`FAM_WriteTool_Service`/`FAM_CapabilitiesTool_Service`) — paritás-garancia,
- * no-duplication (dsgn-003 §6.5). No-auth, lokál, port 39185 (ADR-004).
+ * no-duplication (dsgn-003 §6.5). No-auth, lokál, port 39265 (ADR-004).
  *
  * **Endpoint-felület (a kód-szintű kontraktus — a formális `__documentations/server-api.md` follow-up;
  * dsgn-013 user-jóváhagyásra vár):** lásd a modul `README.md`-jét.
@@ -53,6 +54,7 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
             this.statsEndpoint(),
             this.statsTableEndpoint(),
             this.ingestRunsEndpoint(),
+            this.duplicatesEndpoint(),
             this.configGetEndpoint(),
             this.configSetEndpoint(),
         ];
@@ -135,7 +137,7 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
             endpoint: '/health',
             tasks: [
                 async (req, res) => {
-                    res.send({ ok: true, service: 'fdp-agent-memory', uptime: process.uptime() });
+                    res.send({ ok: true, service: 'fdp-agent-memory', version: fam_version_const_1.FAM_VERSION, uptime: process.uptime() });
                 },
             ],
         });
@@ -284,6 +286,36 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
         return Array.isArray(runTable) ? runTable.some((entry) => String(entry) === table) : String(runTable) === table;
     }
     // =========================================================================
+    // /duplicates/:table — near-duplikátum FELDERÍTŐ (read-only; user-direktíva 2026-06-21)
+    // =========================================================================
+    /**
+     * `GET /duplicates/:table` — egy tár near-duplikátum / multiplikáció scan-je (koszinusz-cluster, NEM töröl).
+     * Query: `threshold` (0..1, default 0.95), `neighbors` (top-K/entry, default 10), `maxEntries` (O(n²)-cap,
+     * default 3000 — a `capped` jelzi, ha a tár nagyobb), `maxClusters` (output-cap, default 100). A `capped`-et
+     * a hívó MINDIG nézze (nincs néma csonkolás).
+     */
+    duplicatesEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'duplicates',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/duplicates/:table',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const table = this.parseTable(req.params.table);
+                        return embedding_1.FAM_DuplicateScan_ControlService.getInstance().scan({
+                            table: table,
+                            threshold: req.query.threshold !== undefined ? Number(req.query.threshold) : undefined,
+                            neighbors: req.query.neighbors !== undefined ? this.parseNumber(req.query.neighbors, 10) : undefined,
+                            maxEntries: req.query.maxEntries !== undefined ? this.parseNumber(req.query.maxEntries, 3000) : undefined,
+                            maxClusters: req.query.maxClusters !== undefined ? this.parseNumber(req.query.maxClusters, 100) : undefined,
+                        });
+                    });
+                },
+            ],
+        });
+    }
+    // =========================================================================
     // /config — scoped config olvasás/írás (dsgn-007; a UI settings + CLI config)
     // =========================================================================
     /**

package/build/src/_routes/server/client-app/client-app.control-service.js

@@ -44,7 +44,7 @@ const FALLBACK_HTML = `<!DOCTYPE html>
   <p>The admin UI is not built yet. Options:</p>
   <ul>
     <li>From the repo: run <code>pnpm run build-ui-for-publish</code> (server), then reload.</li>
-    <li>Dev: start the Angular dev server in <code>client/</code> (<code>pnpm start</code>) at <code>http://localhost:4205</code>.</li>
+    <li>Dev: start the Angular dev server in <code>client/</code> (<code>pnpm start</code>) at <code>http://localhost:4226</code>.</li>
   </ul>
 </body>
 </html>`;

package/build/src/_routes/server/server-status/server-status.controller.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServerStatus_Controller = void 0;
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const fam_version_const_1 = require("../../../_collections/fam-version.const");
 const server_status_control_service_1 = require("./server-status.control-service");
 /**
  * ServerStatus_Controller — saját status endpoint (Pure Dynamo, FDP-mentes).
@@ -25,7 +26,7 @@ class ServerStatus_Controller extends nts_dynamo_1.DyNTS_Controller {
                     async (req, res, issuer) => {
                         res.send({
                             name: 'fdp-agent-memory-server',
-                            version: 'FDP Agent Memory v0.0.1',
+                            version: fam_version_const_1.FAM_VERSION,
                             status: 'ok',
                             uptime: process.uptime(),
                             timestamp: new Date().toISOString(),

package/build/src/app.server.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.App = void 0;
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const logs_1 = require("@futdevpro/nts-dynamo/logs");
 const package_json_1 = require("../package.json");
 const fam_db_models_const_1 = require("./_collections/fam-db-models.const");
 const api_controller_1 = require("./_routes/server/api/api.controller");
@@ -40,7 +41,15 @@ class App extends nts_dynamo_1.DyNTS_App {
     overrideDynamoNTSGlobalSettings() {
         nts_dynamo_1.DyNTS_global_settings.log_settings.api_errors = false;
         nts_dynamo_1.DyNTS_global_settings.log_settings.setup = true;
-        // NINCS JWT/auth check (ADR-004): a szerver lokális, single-user.
+        // NINCS JWT/auth check (ADR-004): a szerver lokális, single-user. Az auth-t EXPLICITEN
+        // opcionálisnak jelöljük → elnémítja a minden booton megjelenő „Unique Authentication Service
+        // missing!" figyelmeztetést (a no-auth a SZÁNDÉK, nem hiányosság).
+        nts_dynamo_1.DyNTS_global_settings.auth_settings.optional = true;
+        // Dynamo KEZELT logs-megoldás (user-direktíva 2026-06-21: „a Dynamo-ban van rá solution, ami elérhetővé
+        // teszi"): a `DyNTS_Logs_Service` buffer-eli a szerver-logokat, és a `/logs` REST-endpoint (no-auth, FAM
+        // lokális) lekérdezhetővé teszi → az agent IS olvashatja REST-en (nem csak a tmp-fájlból). Install + enable.
+        nts_dynamo_1.DyNTS_global_settings.log_settings.logs_endpoint = { enabled: true };
+        logs_1.DyNTS_Logs_Service.getInstance().install();
     }
     getGlobalServiceCollection() {
         return {
@@ -87,6 +96,9 @@ class App extends nts_dynamo_1.DyNTS_App {
                     client_app_controller_1.ClientApp_Controller.getInstance(),
                 ],
             }),
+            // Dynamo KEZELT logs-endpoint — a szerver-logok REST-en lekérdezhetők (`GET /api/logs`, no-auth,
+            // FAM lokális). A `DyNTS_Logs_Service.install()` (fent) buffer-eli; ez a route adja vissza.
+            (0, logs_1.DyNTS_getLogsRoutingModule)(),
             // NB: NINCS DyNTS_getTestRoutingModule / DyNTS_getUsageRoutingModule — a usage-controller
             // `getAuthService()`-t hív (boot-crash a no-auth FAM-on, ADR-004), és egyik Dynamo-leftover
             // route-ot sem használja a FAM (saját ServerStatus_Controller a health-re). FAM-REV-027.

package/build/src/environments/environment.js

@@ -13,7 +13,7 @@ const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
 exports.env = {
     env: process.env.FDP_ENV || nts_dynamo_1.DyNTS_global_settings.env_settings.environment,
     // REST/UI szerver-port (NEM az MCP-stdio — az MVP1-ben stdio, dsgn-012 §4.1).
-    httpPort: +(process.env.FAM_SERVER_PORT || process.env.HTTP_PORT || 39185),
+    httpPort: +(process.env.FAM_SERVER_PORT || process.env.HTTP_PORT || 39265),
     api: {
     // Project-specifikus külső API kulcsok ide kerülnek (pl. embedding-provider, MP-6+).
     },

package/build/src/index.js

@@ -6,7 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 //
 // Indítás:
-//   node build/src/index.js start    → REST szerver (port 39185) + MCP stdio szerver (read/write/capabilities)
+//   node build/src/index.js start    → REST szerver (port 39265) + MCP stdio szerver (read/write/capabilities)
 //   node build/src/index.js          → CSAK REST szerver (visszafelé-kompatibilis; `new App()`)
 //   fam start                        → ugyanaz (a publikált bin a build/src/index.js-re mutat)
 //