@futdevpro/nts-dynamo 1.15.126 → 1.15.127

package/src/_modules/local-vector-search/_services/lvs-persistent-vector-pool.control-service.ts

@@ -1,186 +1,186 @@
-
-import { DyFM_Error, DyFM_Log } from '@futdevpro/fsm-dynamo';
-
-import { LVS_Search_Mode } from '../_enums/lvs-search-mode.enum';
-import { LVS_SearchResult } from '../_models/lvs-search-result.interface';
-import { DyNTS_LVS_VectorPersist } from '../_models/data-models/lvs-vector-persist.data-model';
-import { DyNTS_LVS_VectorPersist_DataService } from './lvs-vector-persist.data-service';
-import { LVS_VectorPool_ControlService } from './lvs-vector-pool.control-service';
-
-/**
- * `DyNTS_LVS_PersistentVectorPool_ControlService` (BFR-AM-001) — egy `LVS_VectorPool_ControlService` in-memory pool +
- * MongoDB-perzisztencia **kompozíciója**. A FAM (fdp-agent-memory) `FAM_VectorSearch_ControlService`
- * persist+hydrate workaround-ját generalizálja bedrock-szintre: a vektorok a SAJÁT Mongo-ban
- * (`dynts_lvs_vector`) élnek, boot-kor a memória-pool-ba hidratálódnak — **NEM** MongoDB Atlas
- * Vector Search.
- *
- * **Miért KOMPOZÍCIÓ (NEM a pool-class módosítása):** a `LVS_VectorPool_ControlService`-t egy másik,
- * párhuzamos WIP (hybrid cosine+BM25) is érinti; a pool-class változtatása merge-konfliktust okozna.
- * Ez a wrapper a pool-t VÁLTOZATLANUL hagyja (delegál: `addVector`/`removeVector`/`updateVector`/
- * `search`), és a perzisztencia-mellékhatást a wrapper-metódusokban végzi. Egy wrapper-instance egy
- * `collectionKey` (logikai pool); több pool = több wrapper.
- *
- * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** a `DyNTS_DataService` base-ctor EAGER
- * `getDBService`-t hív, ezért a wrapper NEM tart élő data-service-mezőt — minden DB-művelet előtt lazy
- * `new DyNTS_LVS_VectorPersist_DataService(...)` (a `getPersistService` ezt adja).
- */
-export class DyNTS_LVS_PersistentVectorPool_ControlService {
-
-  /** A wrapped in-memory pool (a Dynamo LVS engine; VÁLTOZATLAN — kompozíció, nem módosítás). */
-  private readonly pool: LVS_VectorPool_ControlService;
-
-  /** A pool-particionálás kulcsa (a Mongo-rekordok `collectionKey`-e + a hidratálás-szűrő). */
-  private readonly collectionKey: string;
-
-  /** A perzisztencia-műveletek issuer-e (audit). */
-  private readonly issuer: string;
-
-  constructor(set: {
-    collectionKey: string,
-    issuer: string,
-    pool?: LVS_VectorPool_ControlService,
-  }) {
-    this.collectionKey = set.collectionKey;
-    this.issuer = set.issuer;
-    // Saját pool, ha a hívó nem ad be egyet (a wrapper nem módosítja a pool-osztályt — kompozíció).
-    this.pool = set.pool ?? new LVS_VectorPool_ControlService();
-  }
-
-  /** A wrapped in-memory pool (közvetlen olvasáshoz — pl. más search-mód, getAll). */
-  getPool(): LVS_VectorPool_ControlService {
-    return this.pool;
-  }
-
-  /**
-   * Egy vektor felvétele a memória-pool-ba ÉS tartós upsert-je Mongo-ba (persist-on-write, FAM-minta).
-   * A pool `addVector`-ja upsert-szemantikájú (azonos kulcson felülír), a Mongo-oldal is `(collectionKey,
-   * vectorId)`-upsert. A Mongo-írás MELLÉKHATÁS a memória-művelet után (a memória a forrás, a Mongo a tár).
-   */
-  async addVector(vectorId: string, vector: number[], metadata?: unknown): Promise<void> {
-    this.pool.addVector(vectorId, vector);
-    await this.getPersistService().upsertVector({
-      collectionKey: this.collectionKey,
-      vectorId: vectorId,
-      embedding: vector,
-      metadata: metadata,
-    });
-  }
-
-  /**
-   * Egy MEGLÉVŐ vektor frissítése a memória-pool-ban + tartós upsert Mongo-ba. A pool `updateVector`-ja
-   * dob, ha a kulcs nem létezik (a pool-szerződés változatlan) — a Mongo-írás csak siker után fut.
-   */
-  async updateVector(vectorId: string, vector: number[], metadata?: unknown): Promise<void> {
-    this.pool.updateVector(vectorId, vector);
-    await this.getPersistService().upsertVector({
-      collectionKey: this.collectionKey,
-      vectorId: vectorId,
-      embedding: vector,
-      metadata: metadata,
-    });
-  }
-
-  /** Egy vektor eltávolítása a memória-pool-ból ÉS a tartós tárból (`(collectionKey, vectorId)`). */
-  async removeVector(vectorId: string): Promise<void> {
-    this.pool.removeVector(vectorId);
-    await this.getPersistService().removeVector(this.collectionKey, vectorId);
-  }
-
-  /** Keresés a memória-pool-on (a wrapped pool `search`-jét delegálja — VÁLTOZATLAN engine). */
-  search(query: number[], k: number, mode: LVS_Search_Mode): LVS_SearchResult[] {
-    return this.pool.search(query, k, mode);
-  }
-
-  /**
-   * BOOT-HIDRATÁLÁS (FAM-minta, BFR-AM-001): a `collectionKey` ÖSSZES perzistált vektorát betölti a
-   * MEMÓRIA-pool-ba (`pool.addVector`), így a szerver-restart utáni in-memory index újraépül. A pool-t
-   * előbb üríti (idempotens hidratálás). A hiányos (üres `vectorId`/`embedding`) rekordokat átugorja.
-   * Visszaadja a betöltött vektorok számát. **NEM** Atlas — saját Mongo + in-memory pool.
-   */
-  async hydrateFromMongo(set?: {
-    /** Cursor-batch méret (default 500) — a heap-tranziens felső korlátja egy batch. */
-    batchSize?: number,
-    /** Opcionális felső korlát a pool-méretre; elérésekor a hidratálás áll + WARN (no-silent-cap). */
-    maxVectors?: number,
-  }): Promise<number> {
-    // BFR-AM-013 (hydration-paging): a korábbi impl a TELJES collection-t egyetlen
-    // `findByCollectionKey`-jel (Mongoose-doc-tömb) töltötte memóriába → 32k×2560-dim vektornál
-    // RUNTIME-IGAZOLT 93% heap-spike (OOM-közeli). Mostantól LEAN + projektált (vectorId+embedding,
-    // a content-szöveg NÉLKÜL) CURSOR-batch — a tranziens felső korlátja EGY batch.
-    this.pool.clearPool();
-
-    let loaded: number = 0;
-    let skipped: number = 0;
-    let truncated: boolean = false;
-
-    await this.getPersistService().findLeanBatchedByCollectionKey(this.collectionKey, {
-      batchSize: set?.batchSize,
-      handler: (batch: Partial<DyNTS_LVS_VectorPersist>[]): void => {
-        for (const record of batch) {
-          if (truncated) {
-            return;
-          }
-          if (set?.maxVectors !== undefined && loaded >= set.maxVectors) {
-            truncated = true;
-            DyFM_Log.warn(
-              `[DyNTS LVS hydrate] '${this.collectionKey}': maxVectors (${set.maxVectors}) elérve — ` +
-              'a hidratálás CSONKOLVA (no-silent-cap; a maradék vektor NEM került a poolba).',
-            );
-            return;
-          }
-          if (!record.vectorId || !record.embedding?.length) {
-            continue;
-          }
-          try {
-            this.pool.addVector(record.vectorId, record.embedding);
-            loaded++;
-          } catch (error) {
-            // BFR-AM-013 (NaN/±Inf-guard a hidratálásban): EGY hibás (nem-véges elemű) perzistált
-            // vektor NEM boríthatja a teljes boot-hidratálást — skip + warn (nem néma).
-            skipped++;
-            DyFM_Log.warn(
-              `[DyNTS LVS hydrate] '${this.collectionKey}': vektor kihagyva ("${record.vectorId}") — ` +
-              `${DyFM_Error.getErrorMessage(error)}`,
-            );
-          }
-        }
-      },
-    });
-
-    DyFM_Log.log(
-      `[DyNTS LVS hydrate] '${this.collectionKey}' pool: ${loaded} vektor betöltve az in-memory pool-ba` +
-      (skipped ? ` (${skipped} hibás vektor kihagyva)` : '') +
-      (truncated ? ' (CSONKOLT — maxVectors)' : '') + '.',
-    );
-
-    return loaded;
-  }
-
-  /**
-   * Perzistált rekordok közvetlen hidratálása a memória-pool-ba (Mongo-olvasás NÉLKÜL) — ha a hívó már
-   * kezében van a rekord-halmaz (pl. batch-boot). A pool-t előbb üríti (idempotens). Visszaadja a
-   * betöltött vektorok számát.
-   */
-  hydrate(records: DyNTS_LVS_VectorPersist[]): number {
-    this.pool.clearPool();
-    let loaded: number = 0;
-
-    for (const record of records) {
-      if (!record.vectorId || !record.embedding?.length) {
-        continue;
-      }
-      this.pool.addVector(record.vectorId, record.embedding);
-      loaded++;
-    }
-
-    return loaded;
-  }
-
-  /**
-   * Lazy persist-data-service (memory: dynts_dataservice_eager_resolve — a base-ctor eager
-   * `getDBService`-e miatt NEM tartható élő mezőként).
-   */
-  private getPersistService(): DyNTS_LVS_VectorPersist_DataService {
-    return new DyNTS_LVS_VectorPersist_DataService({ issuer: this.issuer });
-  }
-}
+
+import { DyFM_Error, DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import { LVS_Search_Mode } from '../_enums/lvs-search-mode.enum';
+import { LVS_SearchResult } from '../_models/lvs-search-result.interface';
+import { DyNTS_LVS_VectorPersist } from '../_models/data-models/lvs-vector-persist.data-model';
+import { DyNTS_LVS_VectorPersist_DataService } from './lvs-vector-persist.data-service';
+import { LVS_VectorPool_ControlService } from './lvs-vector-pool.control-service';
+
+/**
+ * `DyNTS_LVS_PersistentVectorPool_ControlService` (BFR-AM-001) — egy `LVS_VectorPool_ControlService` in-memory pool +
+ * MongoDB-perzisztencia **kompozíciója**. A FAM (fdp-agent-memory) `FAM_VectorSearch_ControlService`
+ * persist+hydrate workaround-ját generalizálja bedrock-szintre: a vektorok a SAJÁT Mongo-ban
+ * (`dynts_lvs_vector`) élnek, boot-kor a memória-pool-ba hidratálódnak — **NEM** MongoDB Atlas
+ * Vector Search.
+ *
+ * **Miért KOMPOZÍCIÓ (NEM a pool-class módosítása):** a `LVS_VectorPool_ControlService`-t egy másik,
+ * párhuzamos WIP (hybrid cosine+BM25) is érinti; a pool-class változtatása merge-konfliktust okozna.
+ * Ez a wrapper a pool-t VÁLTOZATLANUL hagyja (delegál: `addVector`/`removeVector`/`updateVector`/
+ * `search`), és a perzisztencia-mellékhatást a wrapper-metódusokban végzi. Egy wrapper-instance egy
+ * `collectionKey` (logikai pool); több pool = több wrapper.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** a `DyNTS_DataService` base-ctor EAGER
+ * `getDBService`-t hív, ezért a wrapper NEM tart élő data-service-mezőt — minden DB-művelet előtt lazy
+ * `new DyNTS_LVS_VectorPersist_DataService(...)` (a `getPersistService` ezt adja).
+ */
+export class DyNTS_LVS_PersistentVectorPool_ControlService {
+
+  /** A wrapped in-memory pool (a Dynamo LVS engine; VÁLTOZATLAN — kompozíció, nem módosítás). */
+  private readonly pool: LVS_VectorPool_ControlService;
+
+  /** A pool-particionálás kulcsa (a Mongo-rekordok `collectionKey`-e + a hidratálás-szűrő). */
+  private readonly collectionKey: string;
+
+  /** A perzisztencia-műveletek issuer-e (audit). */
+  private readonly issuer: string;
+
+  constructor(set: {
+    collectionKey: string,
+    issuer: string,
+    pool?: LVS_VectorPool_ControlService,
+  }) {
+    this.collectionKey = set.collectionKey;
+    this.issuer = set.issuer;
+    // Saját pool, ha a hívó nem ad be egyet (a wrapper nem módosítja a pool-osztályt — kompozíció).
+    this.pool = set.pool ?? new LVS_VectorPool_ControlService();
+  }
+
+  /** A wrapped in-memory pool (közvetlen olvasáshoz — pl. más search-mód, getAll). */
+  getPool(): LVS_VectorPool_ControlService {
+    return this.pool;
+  }
+
+  /**
+   * Egy vektor felvétele a memória-pool-ba ÉS tartós upsert-je Mongo-ba (persist-on-write, FAM-minta).
+   * A pool `addVector`-ja upsert-szemantikájú (azonos kulcson felülír), a Mongo-oldal is `(collectionKey,
+   * vectorId)`-upsert. A Mongo-írás MELLÉKHATÁS a memória-művelet után (a memória a forrás, a Mongo a tár).
+   */
+  async addVector(vectorId: string, vector: number[], metadata?: unknown): Promise<void> {
+    this.pool.addVector(vectorId, vector);
+    await this.getPersistService().upsertVector({
+      collectionKey: this.collectionKey,
+      vectorId: vectorId,
+      embedding: vector,
+      metadata: metadata,
+    });
+  }
+
+  /**
+   * Egy MEGLÉVŐ vektor frissítése a memória-pool-ban + tartós upsert Mongo-ba. A pool `updateVector`-ja
+   * dob, ha a kulcs nem létezik (a pool-szerződés változatlan) — a Mongo-írás csak siker után fut.
+   */
+  async updateVector(vectorId: string, vector: number[], metadata?: unknown): Promise<void> {
+    this.pool.updateVector(vectorId, vector);
+    await this.getPersistService().upsertVector({
+      collectionKey: this.collectionKey,
+      vectorId: vectorId,
+      embedding: vector,
+      metadata: metadata,
+    });
+  }
+
+  /** Egy vektor eltávolítása a memória-pool-ból ÉS a tartós tárból (`(collectionKey, vectorId)`). */
+  async removeVector(vectorId: string): Promise<void> {
+    this.pool.removeVector(vectorId);
+    await this.getPersistService().removeVector(this.collectionKey, vectorId);
+  }
+
+  /** Keresés a memória-pool-on (a wrapped pool `search`-jét delegálja — VÁLTOZATLAN engine). */
+  search(query: number[], k: number, mode: LVS_Search_Mode): LVS_SearchResult[] {
+    return this.pool.search(query, k, mode);
+  }
+
+  /**
+   * BOOT-HIDRATÁLÁS (FAM-minta, BFR-AM-001): a `collectionKey` ÖSSZES perzistált vektorát betölti a
+   * MEMÓRIA-pool-ba (`pool.addVector`), így a szerver-restart utáni in-memory index újraépül. A pool-t
+   * előbb üríti (idempotens hidratálás). A hiányos (üres `vectorId`/`embedding`) rekordokat átugorja.
+   * Visszaadja a betöltött vektorok számát. **NEM** Atlas — saját Mongo + in-memory pool.
+   */
+  async hydrateFromMongo(set?: {
+    /** Cursor-batch méret (default 500) — a heap-tranziens felső korlátja egy batch. */
+    batchSize?: number,
+    /** Opcionális felső korlát a pool-méretre; elérésekor a hidratálás áll + WARN (no-silent-cap). */
+    maxVectors?: number,
+  }): Promise<number> {
+    // BFR-AM-013 (hydration-paging): a korábbi impl a TELJES collection-t egyetlen
+    // `findByCollectionKey`-jel (Mongoose-doc-tömb) töltötte memóriába → 32k×2560-dim vektornál
+    // RUNTIME-IGAZOLT 93% heap-spike (OOM-közeli). Mostantól LEAN + projektált (vectorId+embedding,
+    // a content-szöveg NÉLKÜL) CURSOR-batch — a tranziens felső korlátja EGY batch.
+    this.pool.clearPool();
+
+    let loaded: number = 0;
+    let skipped: number = 0;
+    let truncated: boolean = false;
+
+    await this.getPersistService().findLeanBatchedByCollectionKey(this.collectionKey, {
+      batchSize: set?.batchSize,
+      handler: (batch: Partial<DyNTS_LVS_VectorPersist>[]): void => {
+        for (const record of batch) {
+          if (truncated) {
+            return;
+          }
+          if (set?.maxVectors !== undefined && loaded >= set.maxVectors) {
+            truncated = true;
+            DyFM_Log.warn(
+              `[DyNTS LVS hydrate] '${this.collectionKey}': maxVectors (${set.maxVectors}) elérve — ` +
+              'a hidratálás CSONKOLVA (no-silent-cap; a maradék vektor NEM került a poolba).',
+            );
+            return;
+          }
+          if (!record.vectorId || !record.embedding?.length) {
+            continue;
+          }
+          try {
+            this.pool.addVector(record.vectorId, record.embedding);
+            loaded++;
+          } catch (error) {
+            // BFR-AM-013 (NaN/±Inf-guard a hidratálásban): EGY hibás (nem-véges elemű) perzistált
+            // vektor NEM boríthatja a teljes boot-hidratálást — skip + warn (nem néma).
+            skipped++;
+            DyFM_Log.warn(
+              `[DyNTS LVS hydrate] '${this.collectionKey}': vektor kihagyva ("${record.vectorId}") — ` +
+              `${DyFM_Error.getErrorMessage(error)}`,
+            );
+          }
+        }
+      },
+    });
+
+    DyFM_Log.log(
+      `[DyNTS LVS hydrate] '${this.collectionKey}' pool: ${loaded} vektor betöltve az in-memory pool-ba` +
+      (skipped ? ` (${skipped} hibás vektor kihagyva)` : '') +
+      (truncated ? ' (CSONKOLT — maxVectors)' : '') + '.',
+    );
+
+    return loaded;
+  }
+
+  /**
+   * Perzistált rekordok közvetlen hidratálása a memória-pool-ba (Mongo-olvasás NÉLKÜL) — ha a hívó már
+   * kezében van a rekord-halmaz (pl. batch-boot). A pool-t előbb üríti (idempotens). Visszaadja a
+   * betöltött vektorok számát.
+   */
+  hydrate(records: DyNTS_LVS_VectorPersist[]): number {
+    this.pool.clearPool();
+    let loaded: number = 0;
+
+    for (const record of records) {
+      if (!record.vectorId || !record.embedding?.length) {
+        continue;
+      }
+      this.pool.addVector(record.vectorId, record.embedding);
+      loaded++;
+    }
+
+    return loaded;
+  }
+
+  /**
+   * Lazy persist-data-service (memory: dynts_dataservice_eager_resolve — a base-ctor eager
+   * `getDBService`-e miatt NEM tartható élő mezőként).
+   */
+  private getPersistService(): DyNTS_LVS_VectorPersist_DataService {
+    return new DyNTS_LVS_VectorPersist_DataService({ issuer: this.issuer });
+  }
+}