@futdevpro/nts-dynamo 1.15.57 → 1.15.58

package/src/_modules/data-readers/_collections/dynts-sqlite-reader.util.spec.ts

@@ -0,0 +1,161 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import Database from 'better-sqlite3';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_Sqlite_Reader_Util } from './dynts-sqlite-reader.util';
+import { DyNTS_SqliteColumnInfo } from '../_models/interfaces/dynts-sqlite-reader.interface';
+
+/**
+ * `DyNTS_Sqlite_Reader_Util` spec (BFR-AM-009). Egy temp `.db` fájlt hozunk létre (a reader path-szal
+ * + `fileMustExist:true` nyit, ezért valódi fájl kell — a `:memory:` path-ön nem ad fájlt), feltöltjük,
+ * majd igazoljuk:
+ *   - `listTables` (a belső `sqlite_%` táblák kiszűrve, ABC-sorrend),
+ *   - `getSchema` (oszlop-info: name/type/notNull/primaryKey),
+ *   - `readTable` (összes sor) + nem-létező tábla → strukturált hiba,
+ *   - `query` SELECT/WITH fut + paraméteres SELECT,
+ *   - `query` NEM-SELECT (INSERT/UPDATE/DELETE/DROP/multi-statement) → READONLY-hiba (elutasít),
+ *   - hiányzó path / nem-létező fájl → strukturált hiba.
+ */
+describe('DyNTS_Sqlite_Reader_Util (read-only SQLite reader, BFR-AM-009)', () => {
+
+    /** A temp DB-fájl útvonala (minden teszt-futáshoz egyedi). */
+    let dbPath: string;
+
+    beforeAll(() => {
+        dbPath = path.join(os.tmpdir(), `dynts-sqlite-spec-${process.pid}-${Date.now()}.db`);
+        const db: Database.Database = new Database(dbPath);
+        db.exec(`
+            CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, age INTEGER);
+            CREATE TABLE posts (id INTEGER PRIMARY KEY, title TEXT);
+        `);
+        db.prepare('INSERT INTO users (id, name, age) VALUES (?, ?, ?)').run(1, 'Ada', 36);
+        db.prepare('INSERT INTO users (id, name, age) VALUES (?, ?, ?)').run(2, 'Grace', 40);
+        db.prepare('INSERT INTO posts (id, title) VALUES (?, ?)').run(1, 'Hello');
+        db.close();
+    });
+
+    afterAll(() => {
+        if (dbPath && fs.existsSync(dbPath)) {
+            fs.unlinkSync(dbPath);
+        }
+    });
+
+    /** Egy hívás, ami egy adott errorCode-dal kell hogy dobjon (strukturált, NEM néma). */
+    const expectErrorCode = (fn: () => unknown, expectedCode: string): void => {
+        let thrown: unknown;
+        try {
+            fn();
+        } catch (error) {
+            thrown = error;
+        }
+        expect(thrown).withContext(`dobnia kellett (${expectedCode})`).toBeDefined();
+        const code: string | undefined =
+            thrown instanceof DyFM_Error ? DyFM_Error.getErrorCode(thrown) : undefined;
+        expect(code).withContext('a hibakód').toBe(expectedCode);
+    };
+
+    describe('listTables', () => {
+        it('a user-táblák ABC-sorrendben (a belső sqlite_% táblák kiszűrve)', () => {
+            expect(DyNTS_Sqlite_Reader_Util.listTables(dbPath)).toEqual(['posts', 'users']);
+        });
+    });
+
+    describe('getSchema', () => {
+        it('a users tábla oszlop-info-ja (name/type/notNull/primaryKey)', () => {
+            const schema: DyNTS_SqliteColumnInfo[] = DyNTS_Sqlite_Reader_Util.getSchema(dbPath, 'users');
+            expect(schema.map((column) => column.name)).toEqual(['id', 'name', 'age']);
+            const idColumn: DyNTS_SqliteColumnInfo = schema.find((column) => column.name === 'id')!;
+            expect(idColumn.primaryKey).toBe(true);
+            const nameColumn: DyNTS_SqliteColumnInfo = schema.find((column) => column.name === 'name')!;
+            expect(nameColumn.notNull).toBe(true);
+            expect(nameColumn.type).toBe('TEXT');
+        });
+
+        it('nem-létező tábla → DyNTS-SQLITE-READ-002 (NEM néma)', () => {
+            expectErrorCode(() => DyNTS_Sqlite_Reader_Util.getSchema(dbPath, 'no_such_table'), 'DyNTS-SQLITE-READ-002');
+        });
+    });
+
+    describe('readTable', () => {
+        it('a users tábla minden sora', () => {
+            const rows: { id: number; name: string }[] =
+                DyNTS_Sqlite_Reader_Util.readTable(dbPath, 'users') as { id: number; name: string }[];
+            expect(rows.length).toBe(2);
+            expect(rows.map((row) => row.name).sort()).toEqual(['Ada', 'Grace']);
+        });
+
+        it('nem-létező tábla → DyNTS-SQLITE-READ-002 (NEM néma-[])', () => {
+            expectErrorCode(() => DyNTS_Sqlite_Reader_Util.readTable(dbPath, 'ghost'), 'DyNTS-SQLITE-READ-002');
+        });
+    });
+
+    describe('query (SELECT-only)', () => {
+        it('egy SELECT lekérdezés sorai', () => {
+            const rows: { name: string }[] =
+                DyNTS_Sqlite_Reader_Util.query(dbPath, 'SELECT name FROM users ORDER BY age DESC') as { name: string }[];
+            expect(rows.map((row) => row.name)).toEqual(['Grace', 'Ada']);
+        });
+
+        it('paraméteres SELECT (prepared-statement param)', () => {
+            const rows: { name: string }[] =
+                DyNTS_Sqlite_Reader_Util.query(dbPath, 'SELECT * FROM users WHERE age > ?', [37]) as { name: string }[];
+            expect(rows.map((row) => row.name)).toEqual(['Grace']);
+        });
+
+        it('WITH (CTE) is engedett (read-only)', () => {
+            const rows: { n: number }[] = DyNTS_Sqlite_Reader_Util.query(dbPath,
+                'WITH adults AS (SELECT * FROM users WHERE age >= 36) SELECT COUNT(*) AS n FROM adults') as { n: number }[];
+            expect(rows[0].n).toBe(2);
+        });
+
+        it('INSERT → DyNTS-SQLITE-READONLY-001 (elutasít a forrás-rétegben)', () => {
+            expectErrorCode(
+                () => DyNTS_Sqlite_Reader_Util.query(dbPath, "INSERT INTO users (id, name) VALUES (9, 'x')"),
+                'DyNTS-SQLITE-READONLY-001');
+        });
+
+        it('UPDATE → DyNTS-SQLITE-READONLY-001', () => {
+            expectErrorCode(
+                () => DyNTS_Sqlite_Reader_Util.query(dbPath, "UPDATE users SET name='x' WHERE id=1"),
+                'DyNTS-SQLITE-READONLY-001');
+        });
+
+        it('DELETE → DyNTS-SQLITE-READONLY-001', () => {
+            expectErrorCode(
+                () => DyNTS_Sqlite_Reader_Util.query(dbPath, 'DELETE FROM users'),
+                'DyNTS-SQLITE-READONLY-001');
+        });
+
+        it('DROP → DyNTS-SQLITE-READONLY-001', () => {
+            expectErrorCode(
+                () => DyNTS_Sqlite_Reader_Util.query(dbPath, 'DROP TABLE users'),
+                'DyNTS-SQLITE-READONLY-001');
+        });
+
+        it('multi-statement (SELECT; DELETE) → DyNTS-SQLITE-READONLY-001 (nem rejthető írás SELECT mögé)', () => {
+            expectErrorCode(
+                () => DyNTS_Sqlite_Reader_Util.query(dbPath, 'SELECT 1; DELETE FROM users'),
+                'DyNTS-SQLITE-READONLY-001');
+        });
+
+        it('üres SQL → DyNTS-SQLITE-READONLY-001', () => {
+            expectErrorCode(() => DyNTS_Sqlite_Reader_Util.query(dbPath, '   '), 'DyNTS-SQLITE-READONLY-001');
+        });
+    });
+
+    describe('path-validáció (fail-soft, NEM crash)', () => {
+        it('üres path → DyNTS-SQLITE-READ-001', () => {
+            expectErrorCode(() => DyNTS_Sqlite_Reader_Util.listTables(''), 'DyNTS-SQLITE-READ-001');
+        });
+
+        it('nem-létező fájl → DyNTS-SQLITE-READ-001', () => {
+            expectErrorCode(
+                () => DyNTS_Sqlite_Reader_Util.listTables(path.join(os.tmpdir(), 'no-such-db-file-xyz.db')),
+                'DyNTS-SQLITE-READ-001');
+        });
+    });
+});

package/src/_modules/data-readers/_collections/dynts-sqlite-reader.util.ts

@@ -0,0 +1,192 @@
+import * as fs from 'fs';
+
+import Database from 'better-sqlite3';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import {
+    DyNTS_SqliteColumnInfo,
+    DyNTS_SqliteReadOptions,
+} from '../_models/interfaces/dynts-sqlite-reader.interface';
+
+/**
+ * `DyNTS_Sqlite_Reader_Util` (BFR-AM-009) — **read-only** SQLite reader statikus util. Egy IZOLÁLT,
+ * opcionális natív függőséggel (`better-sqlite3`, read-only mode) ad általános, domain-agnosztikus
+ * SQLite-olvasást: `listTables` / `getSchema` / `readTable` / `query` (SELECT-only).
+ *
+ * **Read-only garancia (kétréteg):**
+ *   1. a DB MINDIG `{ readonly: true }`-vel nyílik (a SQLite-engine elutasít minden írást),
+ *   2. a `query()` ráadásul forrás-szinten egy **SELECT-only guard**-ot tesz (csak `SELECT`/`WITH`
+ *      kezdetű, single-statement SQL fut) — így a destruktív SQL még a DB-rétegig sem jut el.
+ *
+ * **Fail-soft (no-silent-failure):** hiányzó `path` / nem-létező fájl / megnyitás-hiba / tiltott SQL
+ * → tiszta, strukturált `DyFM_Error` (errorCode + deskriptív message), NEM hang/crash/néma-[]. A DB
+ * MINDIG zárul (try/finally).
+ *
+ * **Opcionális natív dep:** a `better-sqlite3` peer-dep `optional:true` — a consumer CSAK akkor adja
+ * hozzá, ha SQLite-ot olvas. A `/mcp`-vel diszjunkt; ez a util egy import-ban él, így a require
+ * tényleges hívásig (statikus metódus) nem terheli a nem-SQLite consumert.
+ */
+export class DyNTS_Sqlite_Reader_Util {
+
+    /** A hibák issuer-e (a strukturált DyFM_Error-okhoz). */
+    private static readonly issuer: string = 'DyNTS_Sqlite_Reader_Util';
+
+    /** A `query()` SELECT-only guard regex-e: a (trimmelt, lowercase) SQL `select`/`with`-tel kezdődik. */
+    private static readonly SELECT_ONLY: RegExp = /^\s*(select|with)\b/i;
+
+    /**
+     * Egy tábla ÖSSZES sorának read-only olvasása (`SELECT * FROM <table>`). A `table` nevet
+     * `sqlite_master` ellen validáljuk (csak létező táblanév fut, így nincs SQL-injekciós felület a
+     * tábla-néven). Nem-létező tábla → strukturált hiba (NEM néma-[]).
+     */
+    public static readTable(dbPath: string, table: string): unknown[] {
+        return DyNTS_Sqlite_Reader_Util.withDb(dbPath, (db) => {
+            if (!DyNTS_Sqlite_Reader_Util.tableExists(db, table)) {
+                throw new DyFM_Error({
+                    errorCode: 'DyNTS-SQLITE-READ-002',
+                    message: `Table '${table}' does not exist in the SQLite DB: '${dbPath}'.`,
+                    issuer: DyNTS_Sqlite_Reader_Util.issuer,
+                });
+            }
+            // A `table` itt már egy igazolt, létező táblanév (sqlite_master), nem nyers user-input.
+            return db.prepare(`SELECT * FROM "${table}"`).all();
+        });
+    }
+
+    /**
+     * Egy tetszőleges **SELECT-only** lekérdezés read-only futtatása. A guard elutasít minden nem-SELECT
+     * (insert/update/delete/drop/attach/pragma-write/…) SQL-t → `DyNTS-SQLITE-READONLY-001`. A
+     * `params` opcionális prepared-statement paraméterek (pozícionális `?` vagy named `@x`).
+     */
+    public static query(dbPath: string, sql: string, params?: unknown[] | { [key: string]: unknown }): unknown[] {
+        DyNTS_Sqlite_Reader_Util.assertSelectOnly(sql);
+        return DyNTS_Sqlite_Reader_Util.withDb(dbPath, (db) => {
+            const statement: Database.Statement = db.prepare(sql);
+            // A `better-sqlite3` `.all()` csak read-statement-en ad sort; write-statement-en dobna —
+            // a SELECT-only guard ezt már a forrás-rétegben kizárja (defenzív kettősség).
+            return params === undefined ? statement.all() : statement.all(params as never);
+        });
+    }
+
+    /** A DB ÖSSZES (nem-belső) táblanevének read-only listája (`sqlite_master`, ABC-sorrendben). */
+    public static listTables(dbPath: string): string[] {
+        return DyNTS_Sqlite_Reader_Util.withDb(dbPath, (db) => {
+            const rows: { name: string }[] = db.prepare(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+            ).all() as { name: string }[];
+            return rows.map((row) => row.name);
+        });
+    }
+
+    /**
+     * Egy tábla séma-leírása (`PRAGMA table_info(<table>)` — a SQLite read-only introspekciója). A
+     * `table` nevet `sqlite_master` ellen validáljuk (nem-létező → strukturált hiba). Az oszlop-info
+     * (`cid`/`name`/`type`/`notNull`/`defaultValue`/`primaryKey`) normalizált shape-ben tér vissza.
+     */
+    public static getSchema(dbPath: string, table: string): DyNTS_SqliteColumnInfo[] {
+        return DyNTS_Sqlite_Reader_Util.withDb(dbPath, (db) => {
+            if (!DyNTS_Sqlite_Reader_Util.tableExists(db, table)) {
+                throw new DyFM_Error({
+                    errorCode: 'DyNTS-SQLITE-READ-002',
+                    message: `Table '${table}' does not exist in the SQLite DB: '${dbPath}'.`,
+                    issuer: DyNTS_Sqlite_Reader_Util.issuer,
+                });
+            }
+            const rows: PragmaColumnRow[] = db.pragma(`table_info("${table}")`) as PragmaColumnRow[];
+            return rows.map((row) => ({
+                cid: row.cid,
+                name: row.name,
+                type: row.type,
+                notNull: row.notnull === 1,
+                defaultValue: row.dflt_value,
+                primaryKey: row.pk > 0,
+            }));
+        });
+    }
+
+    // =========================================================================
+    // Belső segédek (read-only megnyitás + guard-ok)
+    // =========================================================================
+
+    /**
+     * A DB read-only megnyitása + a callback futtatása + GARANTÁLT zárás (try/finally). A `path`
+     * validálva (üres/nem-létező → strukturált hiba); a megnyitás-/olvasás-hibát strukturált
+     * `DyFM_Error`-rá fordítjuk (a már-DyFM_Error-t NEM csomagoljuk újra). A `readonly:true` az
+     * első védvonal (a SQLite-engine elutasít minden írást).
+     */
+    private static withDb<T>(dbPath: string, work: (db: Database.Database) => T, options?: DyNTS_SqliteReadOptions): T {
+        if (!dbPath || !dbPath.trim().length) {
+            throw new DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READ-001',
+                message: 'A SQLite read requires a non-empty `dbPath` (path to the `.db` file).',
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+            });
+        }
+        if (!fs.existsSync(dbPath)) {
+            throw new DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READ-001',
+                message: `The SQLite DB file was not found: '${dbPath}'.`,
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+            });
+        }
+        let db: Database.Database | undefined = undefined;
+        try {
+            db = new Database(dbPath, { readonly: true, fileMustExist: true });
+            return work(db);
+        } catch (error) {
+            if (error instanceof DyFM_Error) {
+                throw error;
+            }
+            throw new DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READ-003',
+                message: `Opening/reading the SQLite DB failed: '${dbPath}'.\n  error: `
+                    + `${DyFM_Error.getErrorMessage(error)}`,
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+                error: error,
+            });
+        } finally {
+            if (db) {
+                db.close();
+            }
+        }
+    }
+
+    /** A SELECT-only guard: nem-SELECT/WITH kezdetű VAGY multi-statement SQL → strukturált hiba. */
+    private static assertSelectOnly(sql: string): void {
+        const trimmed: string = (sql ?? '').trim();
+        if (!trimmed.length || !DyNTS_Sqlite_Reader_Util.SELECT_ONLY.test(trimmed)) {
+            throw new DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READONLY-001',
+                message: 'Only read-only SELECT/WITH queries are allowed (the reader is read-only).',
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+            });
+        }
+        // Multi-statement (`;` után további nem-üres tartalom) tiltott — egy SELECT mögé nem rejthető írás.
+        const withoutTrailingSemicolon: string = trimmed.replace(/;\s*$/, '');
+        if (withoutTrailingSemicolon.includes(';')) {
+            throw new DyFM_Error({
+                errorCode: 'DyNTS-SQLITE-READONLY-001',
+                message: 'Multi-statement SQL is not allowed (only a single read-only SELECT/WITH).',
+                issuer: DyNTS_Sqlite_Reader_Util.issuer,
+            });
+        }
+    }
+
+    /** Egy tábla létezésének read-only ellenőrzése (`sqlite_master`). */
+    private static tableExists(db: Database.Database, table: string): boolean {
+        const found: unknown =
+            db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(table);
+        return Boolean(found);
+    }
+}
+
+/** A `PRAGMA table_info` nyers sor-shape-je (a `better-sqlite3` ezt adja vissza). */
+interface PragmaColumnRow {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: string | null;
+    pk: number;
+}

package/src/_modules/data-readers/_models/interfaces/dynts-sqlite-reader.interface.ts

@@ -0,0 +1,33 @@
+/**
+ * A `DyNTS_Sqlite_Reader_Util` (BFR-AM-009) shared shape-jei. Egy fájlban a szorosan összetartozó
+ * SQLite-reader I/O-típusok (`*.interface.ts` az egy-export-per-file konvenció ismert kivétele a
+ * tightly-coupled shape-ekre).
+ */
+
+/**
+ * Egy SQLite tábla egy oszlopának normalizált séma-leírása (a `getSchema()` ezt adja). A nyers
+ * `PRAGMA table_info` sort fordítjuk erre az SDK-független, stabil shape-re.
+ */
+export interface DyNTS_SqliteColumnInfo {
+    /** Az oszlop pozíciós azonosítója a táblában (`PRAGMA table_info.cid`). */
+    cid: number;
+    /** Az oszlop neve. */
+    name: string;
+    /** A deklarált oszlop-típus (SQLite affinity-string, pl. `TEXT`/`INTEGER`; lehet üres). */
+    type: string;
+    /** `true`, ha az oszlop `NOT NULL`. */
+    notNull: boolean;
+    /** Az oszlop default-értéke (deklarált literál string-ként), vagy `null` ha nincs. */
+    defaultValue: string | null;
+    /** `true`, ha az oszlop a primary key (vagy annak része). */
+    primaryKey: boolean;
+}
+
+/**
+ * A read-only megnyitás opciói (jövő-proof bővítő-pont). MVP: üres — a reader MINDIG `readonly:true`
+ * + `fileMustExist:true` módban nyit; ez az interface a későbbi, NON-breaking bővítésnek tart helyet.
+ */
+export interface DyNTS_SqliteReadOptions {
+    /** Reserved (jövőbeli, NON-breaking opciók — pl. timeout/verbose). */
+    reserved?: never;
+}

package/src/_modules/data-readers/index.ts

@@ -0,0 +1,11 @@
+
+
+// DATA-READERS MODULE — domain-agnosztikus, read-only külső-adatforrás olvasók (NEM Mongo). Jelenleg:
+// `DyNTS_Sqlite_Reader_Util` (BFR-AM-009) — read-only SQLite reader (`better-sqlite3`, opcionális
+// natív peer-dep). SELECT-only guard + fail-soft strukturált hibák.
+
+// INTERFACES
+export * from './_models/interfaces/dynts-sqlite-reader.interface';
+
+// COLLECTIONS (utils)
+export * from './_collections/dynts-sqlite-reader.util';

package/src/_modules/local-vector-search/_models/data-models/lvs-vector-persist.data-model.ts

@@ -0,0 +1,59 @@
+
+import { DyFM_DataModel_Params, DyFM_Metadata, DyFM_Object } from '@futdevpro/fsm-dynamo';
+
+/**
+ * `DyNTS_LVS_VectorPersist_DataModel` (BFR-AM-001) — egy MongoDB-ben perzistált vektor-rekord, ami a
+ * `LVS_VectorPool_ControlService` **in-memory** pool-jának tartós háttértára. A FAM (fdp-agent-memory)
+ * workaround-ját generalizálja: a vektorok a SAJÁT Mongo-ban élnek, boot-kor a memória-pool-ba
+ * hidratálódnak — **NEM** MongoDB Atlas Vector Search.
+ *
+ * Egy dokumentum = **egy vektor egy adott pool-ban**. A `collectionKey` particionálja a pool-okat
+ * (egy fogyasztó több, logikailag elkülönített pool-t tarthat — pl. táranként). A `vectorId` a pool-on
+ * belüli kulcs (a `pool.addVector(vectorId, embedding)` ezzel illeszt).
+ *
+ * `extends DyFM_Metadata`: az identitás/metadata (`_id`, `__created`, `__lastModified`, `_deleted`) az
+ * ősből jön. A `metadata` `unknown` (Mongoose `Mixed`) — a fogyasztó tetszőleges kísérő-adatot tárolhat
+ * (a séma NEM validál); az `embedding` `number[]` a perzistált nyers vektor.
+ */
+export class DyNTS_LVS_VectorPersist_DataModel extends DyFM_Metadata {
+
+  /** A pool-on belüli vektor-kulcs (a `pool.addVector(vectorId, ...)` ezzel illeszt). */
+  vectorId?: string;
+
+  /** Melyik (logikai) pool-hoz tartozik — a pool-particionálás kulcsa (hidratálás-szűrő). */
+  collectionKey?: string;
+
+  /** A perzistált NYERS vektor (a pool maga számolja a normalizált másolatot). */
+  embedding?: number[];
+
+  /** A vektor dimenziója (homogenitás-ellenőrzéshez + diagnosztikához tárolt). */
+  dimensions?: number;
+
+  /** Opcionális fogyasztó-specifikus kísérő-adat (Mongoose `Mixed`; a séma NEM validál). */
+  metadata?: unknown;
+
+  constructor(set?: Partial<DyNTS_LVS_VectorPersist_DataModel>) {
+    super(set);
+    if (set) {
+      DyFM_Object.cleanAssign(this, set);
+    }
+  }
+}
+
+/**
+ * MongoDB data-params a `dynts_lvs_vector` collection-höz (BFR-AM-001). Az `embedding` `number[]` a
+ * perzistált nyers vektor; a `metadata` `type:'object'` (Mongoose `Mixed`) — a séma NEM validál. A
+ * `vectorId` + `collectionKey` index-elt (a hidratálás `collectionKey`-re, az upsert/remove a
+ * `vectorId`+`collectionKey` párra szűr).
+ */
+export const dyNTS_lvsVectorPersist_dataParams: DyFM_DataModel_Params<DyNTS_LVS_VectorPersist_DataModel> =
+  new DyFM_DataModel_Params<DyNTS_LVS_VectorPersist_DataModel>({
+    dataName: 'dynts_lvs_vector',
+    properties: {
+      vectorId: { type: 'string', index: true, required: true },
+      collectionKey: { type: 'string', index: true, required: true },
+      embedding: { type: 'number[]' },
+      dimensions: { type: 'number' },
+      metadata: { type: 'object' },
+    },
+  });

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);
+  });
+});