@futdevpro/nts-dynamo 1.15.56 → 1.15.58

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

@@ -0,0 +1,198 @@
+
+import { DyFM_EnvironmentFlag } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../../_collections/global-settings.const';
+import { DyNTS_GlobalService } from '../../../_services/core/global.service';
+import { LVS_Search_Mode } from '../_enums/lvs-search-mode.enum';
+import { LVS_SearchResult } from '../_models/lvs-search-result.interface';
+import { DyNTS_LVS_VectorPersist_DataModel } from '../_models/data-models/lvs-vector-persist.data-model';
+import { DyNTS_LVS_VectorPersist_DataService } from './lvs-vector-persist.data-service';
+import { DyNTS_LVS_PersistentVectorPool } from './lvs-persistent-vector-pool.control-service';
+
+/**
+ * BFR-AM-001 — a `DyNTS_LVS_PersistentVectorPool` (kompozíció: in-memory pool + Mongo-persist) spec-jei.
+ *
+ * A DB-réteget egy IN-MEMORY fake-store helyettesíti: a `DyNTS_LVS_VectorPersist_DataService.prototype`
+ * `upsertVector`/`removeVector`/`findByCollectionKey` metódusait stub-oljuk (a `getDBService` eager
+ * base-ctor-t is, hogy a lazy data-service-példányok ne dobjanak — memory: dynts_dataservice_eager_resolve),
+ * így a perzisztencia memóriában modellezett, ÉLŐ Mongo nélkül (skip-guard nem szükséges). A fő bizonyíték:
+ * **persist-then-hydrate round-trip** újraépíti a VALÓDI `LVS_VectorPool_ControlService` in-memory indexét.
+ */
+describe('| DyNTS_LVS_PersistentVectorPool', () => {
+
+  let mockDBService: jasmine.SpyObj<{ find: () => Promise<unknown[]>; findOne: () => Promise<unknown> }>;
+
+  /** Fake tartós tár: `collectionKey` → (`vectorId` → rekord). A persist-stubok ezt írják/olvassák. */
+  let store: Map<string, Map<string, DyNTS_LVS_VectorPersist_DataModel>>;
+
+  beforeAll(() => {
+    if (!DyNTS_global_settings.systemShortCodeName) {
+      (DyNTS_global_settings as { systemShortCodeName?: string }).systemShortCodeName = 'TEST';
+    }
+    if (!DyNTS_global_settings.env_settings) {
+      (DyNTS_global_settings as { env_settings?: unknown }).env_settings = {
+        environment: DyFM_EnvironmentFlag.local,
+      };
+    }
+  });
+
+  beforeEach(() => {
+    // A base-ctor eager getDBService-jét stub-oljuk (a lazy persist-service ne dobjon).
+    mockDBService = jasmine.createSpyObj('DyNTS_DBService', ['find', 'findOne']);
+    mockDBService.find.and.returnValue(Promise.resolve([]));
+    mockDBService.findOne.and.returnValue(Promise.resolve(null));
+    spyOn(DyNTS_GlobalService, 'getDBService').and.returnValue(mockDBService as never);
+
+    // A fake tartós tár + a persist-service prototype-stubok (memóriában modellezett Mongo).
+    store = new Map<string, Map<string, DyNTS_LVS_VectorPersist_DataModel>>();
+
+    spyOn(DyNTS_LVS_VectorPersist_DataService.prototype, 'upsertVector').and.callFake(
+      (set: { collectionKey: string; vectorId: string; embedding: number[]; metadata?: unknown }) => {
+        let coll: Map<string, DyNTS_LVS_VectorPersist_DataModel> | undefined = store.get(set.collectionKey);
+        if (!coll) {
+          coll = new Map<string, DyNTS_LVS_VectorPersist_DataModel>();
+          store.set(set.collectionKey, coll);
+        }
+        coll.set(set.vectorId, new DyNTS_LVS_VectorPersist_DataModel({
+          collectionKey: set.collectionKey,
+          vectorId: set.vectorId,
+          embedding: set.embedding,
+          dimensions: set.embedding.length,
+          metadata: set.metadata,
+        }));
+        return Promise.resolve();
+      },
+    );
+
+    spyOn(DyNTS_LVS_VectorPersist_DataService.prototype, 'removeVector').and.callFake(
+      (collectionKey: string, vectorId: string) => {
+        store.get(collectionKey)?.delete(vectorId);
+        return Promise.resolve();
+      },
+    );
+
+    spyOn(DyNTS_LVS_VectorPersist_DataService.prototype, 'findByCollectionKey').and.callFake(
+      (collectionKey: string) =>
+        Promise.resolve(Array.from(store.get(collectionKey)?.values() ?? [])),
+    );
+  });
+
+  /** Egy egységvektor a tengely-irányba (cosine-self = 1) — determinisztikus keresés-ellenőrzéshez. */
+  const axis = (dim: number, hot: number): number[] => {
+    const v: number[] = new Array<number>(dim).fill(0);
+    v[hot] = 1;
+    return v;
+  };
+
+  it('| should persist on addVector and store the dimension', async () => {
+    const pool: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+
+    await pool.addVector('v1', [0.1, 0.2, 0.3], { tag: 'x' });
+
+    const persisted: DyNTS_LVS_VectorPersist_DataModel | undefined = store.get('pool-a')?.get('v1');
+    expect(persisted).toBeDefined();
+    expect(persisted.embedding).toEqual([0.1, 0.2, 0.3]);
+    expect(persisted.dimensions).toBe(3);
+    expect(persisted.metadata).toEqual({ tag: 'x' });
+    // és a memória-pool-ban is benne van (kereshető):
+    expect(pool.getPool().getAll().size).toBe(1);
+  });
+
+  it('| persist-then-hydrate round-trip rebuilds the in-memory pool', async () => {
+    // (1) Egy pool-ba 3 vektort persistálunk.
+    const writer: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+    await writer.addVector('v0', axis(4, 0));
+    await writer.addVector('v1', axis(4, 1));
+    await writer.addVector('v2', axis(4, 2));
+    expect(store.get('pool-a').size).toBe(3);
+
+    // (2) Egy FRISS wrapper (üres memória-pool) — szerver-restart szimuláció.
+    const rebuilt: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+    expect(rebuilt.getPool().getAll().size).toBe(0);
+
+    // (3) Hidratálás Mongo-ból → a memória-pool újraépül.
+    const loaded: number = await rebuilt.hydrateFromMongo();
+    expect(loaded).toBe(3);
+    expect(rebuilt.getPool().getAll().size).toBe(3);
+
+    // (4) A keresés a hidratált pool-on a helyes vektort hozza vissza (cosine self-match = 1).
+    const hits: LVS_SearchResult[] = rebuilt.search(axis(4, 1), 1, LVS_Search_Mode.cosineSimilarity);
+    expect(hits.length).toBe(1);
+    expect(hits[0].id).toBe('v1');
+    expect(hits[0].score).toBeCloseTo(1, 6);
+  });
+
+  it('| should only hydrate the matching collectionKey (pool partitioning)', async () => {
+    const a: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+    const b: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-b', issuer: 'test' });
+
+    await a.addVector('a1', axis(3, 0));
+    await b.addVector('b1', axis(3, 1));
+    await b.addVector('b2', axis(3, 2));
+
+    const rebuiltA: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+    expect(await rebuiltA.hydrateFromMongo()).toBe(1);
+    expect(Array.from(rebuiltA.getPool().getAll().keys())).toEqual(['a1']);
+  });
+
+  it('| upsert (re-add) is reflected in both the pool and the store', async () => {
+    const pool: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+
+    await pool.addVector('v1', [1, 0, 0]);
+    await pool.updateVector('v1', [0, 1, 0], { v: 2 });
+
+    // a tárban EGY rekord van, a frissített értékkel + dimenzióval:
+    expect(store.get('pool-a').size).toBe(1);
+    const persisted: DyNTS_LVS_VectorPersist_DataModel = store.get('pool-a').get('v1');
+    expect(persisted.embedding).toEqual([0, 1, 0]);
+    expect(persisted.dimensions).toBe(3);
+    expect(persisted.metadata).toEqual({ v: 2 });
+
+    // és egy friss hidratálás a frissített vektort hozza:
+    const rebuilt: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+    await rebuilt.hydrateFromMongo();
+    const hits: LVS_SearchResult[] = rebuilt.search([0, 1, 0], 1, LVS_Search_Mode.cosineSimilarity);
+    expect(hits[0].id).toBe('v1');
+    expect(hits[0].score).toBeCloseTo(1, 6);
+  });
+
+  it('| removeVector is reflected in both the pool and the store', async () => {
+    const pool: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+
+    await pool.addVector('v1', axis(3, 0));
+    await pool.addVector('v2', axis(3, 1));
+    expect(store.get('pool-a').size).toBe(2);
+
+    await pool.removeVector('v1');
+
+    expect(store.get('pool-a').size).toBe(1);
+    expect(store.get('pool-a').has('v1')).toBeFalse();
+    expect(pool.getPool().getAll().has('v1')).toBeFalse();
+    expect(pool.getPool().getAll().has('v2')).toBeTrue();
+  });
+
+  it('| hydrate(records) rebuilds the pool without a Mongo read and skips incomplete records', () => {
+    const pool: DyNTS_LVS_PersistentVectorPool =
+      new DyNTS_LVS_PersistentVectorPool({ collectionKey: 'pool-a', issuer: 'test' });
+
+    const loaded: number = pool.hydrate([
+      new DyNTS_LVS_VectorPersist_DataModel({ collectionKey: 'pool-a', vectorId: 'v1', embedding: axis(2, 0) }),
+      new DyNTS_LVS_VectorPersist_DataModel({ collectionKey: 'pool-a', vectorId: 'v2', embedding: axis(2, 1) }),
+      // hiányos rekordok (átugorva):
+      new DyNTS_LVS_VectorPersist_DataModel({ collectionKey: 'pool-a', vectorId: 'v3', embedding: [] }),
+      new DyNTS_LVS_VectorPersist_DataModel({ collectionKey: 'pool-a', embedding: axis(2, 0) }),
+    ]);
+
+    expect(loaded).toBe(2);
+    expect(pool.getPool().getAll().size).toBe(2);
+  });
+});

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

@@ -0,0 +1,146 @@
+
+import { 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_DataModel } 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` (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 {
+
+  /** 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(): Promise<number> {
+    const records: DyNTS_LVS_VectorPersist_DataModel[] =
+      await this.getPersistService().findByCollectionKey(this.collectionKey);
+
+    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++;
+    }
+
+    DyFM_Log.log(
+      `[DyNTS LVS hydrate] '${this.collectionKey}' pool: ${loaded} vektor betöltve az in-memory pool-ba.`,
+    );
+    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_DataModel[]): 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 });
+  }
+}

package/src/_modules/local-vector-search/_services/lvs-vector-persist.data-service.spec.ts

@@ -0,0 +1,167 @@
+
+import { DyFM_EnvironmentFlag } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../../_collections/global-settings.const';
+import { DyNTS_GlobalService } from '../../../_services/core/global.service';
+import { DyNTS_LVS_VectorPersist_DataModel } from '../_models/data-models/lvs-vector-persist.data-model';
+import { DyNTS_LVS_VectorPersist_DataService } from './lvs-vector-persist.data-service';
+
+/**
+ * BFR-AM-001 — a `DyNTS_LVS_VectorPersist_DataService` spec-jei. A base-ctor eager `getDBService`-jét
+ * stub-oljuk (memory: dynts_dataservice_eager_resolve), így NEM kell élő Mongo. Az upsert atomikus
+ * `$set`-jét (Mixed `metadata` — memory: mongoose_mixed_atomic_write) + a dimenzió-tárolást bizonyítja.
+ */
+describe('| DyNTS_LVS_VectorPersist_DataService', () => {
+
+  let mockDBService: jasmine.SpyObj<{ find: () => Promise<unknown[]>; findOne: () => Promise<unknown> }>;
+
+  beforeAll(() => {
+    if (!DyNTS_global_settings.systemShortCodeName) {
+      (DyNTS_global_settings as { systemShortCodeName?: string }).systemShortCodeName = 'TEST';
+    }
+    if (!DyNTS_global_settings.env_settings) {
+      (DyNTS_global_settings as { env_settings?: unknown }).env_settings = {
+        environment: DyFM_EnvironmentFlag.local,
+      };
+    }
+  });
+
+  beforeEach(() => {
+    mockDBService = jasmine.createSpyObj('DyNTS_DBService', ['find', 'findOne']);
+    mockDBService.find.and.returnValue(Promise.resolve([]));
+    mockDBService.findOne.and.returnValue(Promise.resolve(null));
+    spyOn(DyNTS_GlobalService, 'getDBService').and.returnValue(mockDBService as never);
+  });
+
+  describe('| constructor', () => {
+
+    it('| should create the service with a data model', () => {
+      const data: DyNTS_LVS_VectorPersist_DataModel = new DyNTS_LVS_VectorPersist_DataModel({
+        collectionKey: 'pool-a',
+        vectorId: 'v1',
+        embedding: [1, 2, 3],
+      });
+
+      const service: DyNTS_LVS_VectorPersist_DataService =
+        new DyNTS_LVS_VectorPersist_DataService({ data: data, issuer: 'issuer-123' });
+
+      expect(service).toBeInstanceOf(DyNTS_LVS_VectorPersist_DataService);
+      expect(service.data).toBeDefined();
+      expect(service.data.vectorId).toBe('v1');
+      expect(service.data.collectionKey).toBe('pool-a');
+    });
+
+    it('| should create the service without data', () => {
+      const service: DyNTS_LVS_VectorPersist_DataService =
+        new DyNTS_LVS_VectorPersist_DataService({ issuer: 'issuer-123' });
+
+      expect(service).toBeInstanceOf(DyNTS_LVS_VectorPersist_DataService);
+      expect(service.data).toBeInstanceOf(DyNTS_LVS_VectorPersist_DataModel);
+    });
+  });
+
+  describe('| findByCollectionKey', () => {
+
+    it('| should query the persisted vectors for a collectionKey', async () => {
+      const service: DyNTS_LVS_VectorPersist_DataService =
+        new DyNTS_LVS_VectorPersist_DataService({ issuer: 'issuer-123' });
+
+      const records: DyNTS_LVS_VectorPersist_DataModel[] = [
+        new DyNTS_LVS_VectorPersist_DataModel({ collectionKey: 'pool-a', vectorId: 'v1', embedding: [1, 0] }),
+      ];
+      const findSpy = spyOn(service, 'findDataList').and.returnValue(Promise.resolve(records));
+
+      const result: DyNTS_LVS_VectorPersist_DataModel[] = await service.findByCollectionKey('pool-a');
+
+      expect(findSpy).toHaveBeenCalledTimes(1);
+      const filterArg = findSpy.calls.mostRecent().args[0] as { collectionKey: string };
+      expect(filterArg.collectionKey).toBe('pool-a');
+      expect(result).toBe(records);
+    });
+  });
+
+  describe('| upsertVector — atomic $set + dimension store', () => {
+
+    it('| should issue an updateOne $set (with dimensions) for an EXISTING record', async () => {
+      const service: DyNTS_LVS_VectorPersist_DataService =
+        new DyNTS_LVS_VectorPersist_DataService({ issuer: 'issuer-123' });
+
+      const existing: DyNTS_LVS_VectorPersist_DataModel = new DyNTS_LVS_VectorPersist_DataModel({
+        collectionKey: 'pool-a', vectorId: 'v1', embedding: [1, 2, 3],
+      });
+      existing._id = 'rec-1';
+
+      spyOn(service, 'findData').and.returnValue(Promise.resolve(existing));
+      const updateSpy = spyOn(service, 'updateData').and.returnValue(Promise.resolve());
+      const saveSpy = spyOn(service, 'saveData').and.returnValue(Promise.resolve(existing));
+
+      await service.upsertVector({
+        collectionKey: 'pool-a', vectorId: 'v1', embedding: [4, 5, 6, 7], metadata: { tag: 'x' },
+      });
+
+      expect(saveSpy).not.toHaveBeenCalled();
+      expect(updateSpy).toHaveBeenCalledTimes(1);
+      const arg = updateSpy.calls.mostRecent().args[0] as {
+        filterBy: { _id: string };
+        update: { $set: { embedding: number[]; dimensions: number; metadata: unknown } };
+      };
+      expect(arg.filterBy._id).toBe('rec-1');
+      expect(arg.update.$set.embedding).toEqual([4, 5, 6, 7]);
+      expect(arg.update.$set.dimensions).toBe(4);
+      expect(arg.update.$set.metadata).toEqual({ tag: 'x' });
+    });
+
+    it('| should saveData a NEW record (with stored dimensions) when none exists', async () => {
+      const service: DyNTS_LVS_VectorPersist_DataService =
+        new DyNTS_LVS_VectorPersist_DataService({ issuer: 'issuer-123' });
+
+      spyOn(service, 'findData').and.returnValue(Promise.resolve(null));
+      const updateSpy = spyOn(service, 'updateData').and.returnValue(Promise.resolve());
+      const saveSpy = spyOn(service, 'saveData')
+        .and.callFake((data?: DyNTS_LVS_VectorPersist_DataModel) =>
+          Promise.resolve(data as DyNTS_LVS_VectorPersist_DataModel));
+
+      await service.upsertVector({ collectionKey: 'pool-a', vectorId: 'v2', embedding: [0.1, 0.2] });
+
+      expect(updateSpy).not.toHaveBeenCalled();
+      expect(saveSpy).toHaveBeenCalledTimes(1);
+      const written = saveSpy.calls.mostRecent().args[0] as DyNTS_LVS_VectorPersist_DataModel;
+      expect(written.vectorId).toBe('v2');
+      expect(written.collectionKey).toBe('pool-a');
+      expect(written.embedding).toEqual([0.1, 0.2]);
+      expect(written.dimensions).toBe(2);
+    });
+  });
+
+  describe('| removeVector', () => {
+
+    it('| should absolute-delete the matching record', async () => {
+      const service: DyNTS_LVS_VectorPersist_DataService =
+        new DyNTS_LVS_VectorPersist_DataService({ issuer: 'issuer-123' });
+
+      const existing: DyNTS_LVS_VectorPersist_DataModel = new DyNTS_LVS_VectorPersist_DataModel({
+        collectionKey: 'pool-a', vectorId: 'v1', embedding: [1, 0],
+      });
+      existing._id = 'rec-1';
+
+      spyOn(service, 'findData').and.returnValue(Promise.resolve(existing));
+      const deleteSpy = spyOn(service, 'deleteData').and.returnValue(Promise.resolve());
+
+      await service.removeVector('pool-a', 'v1');
+
+      expect(deleteSpy).toHaveBeenCalledWith('rec-1', true);
+    });
+
+    it('| should be a no-op when no matching record exists', async () => {
+      const service: DyNTS_LVS_VectorPersist_DataService =
+        new DyNTS_LVS_VectorPersist_DataService({ issuer: 'issuer-123' });
+
+      spyOn(service, 'findData').and.returnValue(Promise.resolve(null));
+      const deleteSpy = spyOn(service, 'deleteData').and.returnValue(Promise.resolve());
+
+      await service.removeVector('pool-a', 'missing');
+
+      expect(deleteSpy).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/_modules/local-vector-search/_services/lvs-vector-persist.data-service.ts

@@ -0,0 +1,106 @@
+
+import { DyFM_DBFilter, DyFM_DBFilterSimple } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_DataService } from '../../../_services/base/data.service';
+import {
+  DyNTS_LVS_VectorPersist_DataModel,
+  dyNTS_lvsVectorPersist_dataParams,
+} from '../_models/data-models/lvs-vector-persist.data-model';
+
+/**
+ * `DyNTS_LVS_VectorPersist_DataService` (BFR-AM-001) — a `dynts_lvs_vector` collection CRUD-rétege; a
+ * `LVS_VectorPool_ControlService` in-memory pool-jának tartós Mongo-háttértára. `extends
+ * DyNTS_DataService`; a nts-konvenció szerinti `{ data?, issuer }` constructor.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** a `DyNTS_DataService` base-ctor EAGER
+ * `getDBService`-t hív → a hívó NEM tarthat élő data-service-példányt mezőként; minden művelet előtt
+ * lazy `new DyNTS_LVS_VectorPersist_DataService(...)` kell (a `DyNTS_LVS_PersistentVectorPool` így jár el).
+ *
+ * **Atomikus írás (memory: mongoose_mixed_atomic_write):** az upsert a `(collectionKey, vectorId)`
+ * logikai-kulcson MEGLÉVŐ rekordot `updateOne({...},{$set:{embedding,dimensions,metadata}})`-tel
+ * frissíti (a Mixed `metadata` `findOne→mutate→save` SILENT-DROP-ja ellen); ÚJ rekordot `saveData`-val ír.
+ */
+export class DyNTS_LVS_VectorPersist_DataService extends DyNTS_DataService<DyNTS_LVS_VectorPersist_DataModel> {
+
+  constructor(
+    set: {
+      data?: DyNTS_LVS_VectorPersist_DataModel,
+      issuer: string,
+    },
+  ) {
+    super(
+      set.data instanceof DyNTS_LVS_VectorPersist_DataModel
+        ? set.data
+        : new DyNTS_LVS_VectorPersist_DataModel(set.data),
+      dyNTS_lvsVectorPersist_dataParams,
+      set.issuer,
+    );
+  }
+
+  /**
+   * Egy (logikai) pool ÖSSZES perzistált, nem-soft-delete-elt vektor-rekordja — a boot-hidratáláshoz
+   * (a `DyNTS_LVS_PersistentVectorPool.hydrateFromMongo` ezt tölti az in-memory pool-ba).
+   */
+  async findByCollectionKey(collectionKey: string): Promise<DyNTS_LVS_VectorPersist_DataModel[]> {
+    return this.findDataList(
+      { collectionKey: collectionKey } as DyFM_DBFilterSimple<DyNTS_LVS_VectorPersist_DataModel>,
+      true,
+    );
+  }
+
+  /**
+   * Egy vektor ATOMIKUS upsert-je a `(collectionKey, vectorId)` logikai-kulcson. MEGLÉVŐ rekordnál
+   * `$set` (a Mixed `metadata` silent-drop ellen — memory: mongoose_mixed_atomic_write); ÚJ rekordnál
+   * `saveData`. A dimenzió az `embedding.length`-ből rögzül.
+   */
+  async upsertVector(set: {
+    collectionKey: string,
+    vectorId: string,
+    embedding: number[],
+    metadata?: unknown,
+  }): Promise<void> {
+    const existing: DyNTS_LVS_VectorPersist_DataModel = await this.findData(
+      { collectionKey: set.collectionKey, vectorId: set.vectorId } as DyFM_DBFilter<DyNTS_LVS_VectorPersist_DataModel>,
+      true,
+    );
+
+    if (existing?._id) {
+      await this.updateData({
+        filterBy: { _id: existing._id } as DyFM_DBFilterSimple<DyNTS_LVS_VectorPersist_DataModel>,
+        update: {
+          $set: {
+            embedding: set.embedding,
+            dimensions: set.embedding.length,
+            metadata: set.metadata,
+          },
+        },
+      });
+      return;
+    }
+
+    await this.saveData(
+      new DyNTS_LVS_VectorPersist_DataModel({
+        collectionKey: set.collectionKey,
+        vectorId: set.vectorId,
+        embedding: set.embedding,
+        dimensions: set.embedding.length,
+        metadata: set.metadata,
+      }),
+      true,
+    );
+  }
+
+  /**
+   * Egy vektor-rekord végleges törlése a `(collectionKey, vectorId)` logikai-kulcson (a pool
+   * `removeVector`-ja után — a tartós tár is törli). `addArchive` nincs → `absolute` true-val töröl.
+   */
+  async removeVector(collectionKey: string, vectorId: string): Promise<void> {
+    const existing: DyNTS_LVS_VectorPersist_DataModel = await this.findData(
+      { collectionKey: collectionKey, vectorId: vectorId } as DyFM_DBFilter<DyNTS_LVS_VectorPersist_DataModel>,
+      true,
+    );
+    if (existing?._id) {
+      await this.deleteData(existing._id, true);
+    }
+  }
+}