@futdevpro/nts-dynamo 1.15.57 → 1.15.58

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

package/src/_modules/local-vector-search/index.ts

@@ -6,7 +6,12 @@ export * from './_enums/lvs-search-mode.enum';
 // INTERFACES
 export * from './_models/lvs-search-result.interface';
 
+// DATA MODELS
+export * from './_models/data-models/lvs-vector-persist.data-model';
+
 // SERVICES
 export * from './_services/lvs-doc-chunk-data.service';
 export * from './_services/lvs-local-vector-search.data-service';
-export * from './_services/lvs-vector-pool.control-service';
+export * from './_services/lvs-vector-pool.control-service';
+export * from './_services/lvs-vector-persist.data-service';
+export * from './_services/lvs-persistent-vector-pool.control-service';

package/src/_modules/mcp/_models/interfaces/dynts-mcp.interface.ts

@@ -0,0 +1,111 @@
+/**
+ * MCP-réteg shared vokabulár (BFR-AM-003) — a domain-agnosztikus MCP-szerver-base + adaptor közös
+ * típusai. Egy fájlban a szorosan összetartozó tool-/transport-típusok (`*.interface.ts` az
+ * egy-export-per-file konvenció ismert kivétele a tightly-coupled shape-ekre).
+ *
+ * Boundary: a `DyNTS_McpToolDefinition` + a `DyNTS_Mcp_Adapter` egyetlen `registerTool` choke-pontot
+ * ad — a hivatalos `@modelcontextprotocol/sdk` KIZÁRÓLAG az adaptor mögött él, így egy jövőbeli
+ * transport-/SDK-csere NEM-breaking (csak az adaptor cserélődik, a `DyNTS_Mcp_ServerBase` + a
+ * consumer-tool-ok változatlanok). A consumer a SAJÁT tool-jait regisztrálja (a bedrock NEM definiál
+ * domain-tool-okat — csak a server-base + a transport + a registry).
+ */
+
+/**
+ * Egy JSON-schema fragment (a tool input-schema-jának típusa). Szabad-formájú JSON-objektum (a
+ * draft-07 / MCP tool-schema dialektusa); a `properties`/`required`/`type` mezők gyakoriak, de a
+ * shape nem kényszerített (az MCP-kliens a `tools/list`-ben kapja vissza, ahogy van).
+ */
+export interface DyNTS_Mcp_JsonSchema {
+    /** A JSON-schema gyökér-típusa (a tool input-ja jellemzően `object`). */
+    type: string;
+    /** A property-leírások (kulcs → al-schema). */
+    properties?: { [key: string]: DyNTS_Mcp_JsonSchema };
+    /** Kötelező property-nevek. */
+    required?: string[];
+    /** Array-elem schema (`type: 'array'` esetén). */
+    items?: DyNTS_Mcp_JsonSchema;
+    /** Enum-értékek (string/number/boolean literál-halmaz). */
+    enum?: (string | number | boolean)[];
+    /** Emberi leírás (a tool-választáshoz; az LLM ezt olvassa). */
+    description?: string;
+    /** Default érték (a kliens-hint). */
+    default?: unknown;
+    /** Engedi-e a nem-leírt property-ket (`object` schema-n). */
+    additionalProperties?: boolean;
+    /** Beágyazott `oneOf`/`anyOf` alternatívák. */
+    oneOf?: DyNTS_Mcp_JsonSchema[];
+}
+
+/**
+ * Egy MCP tool-handler kimenete (a transport-agnosztikus core ezt adja; az adaptor MCP-tool-result-tá
+ * fordítja). A `data` a strukturált JSON-payload; az `isError` jelzi a strukturált hibát — a néma
+ * hiba TILOS (a hiba MINDIG `isError:true` payload VAGY dobott exception, amit az adaptor egységesen
+ * `isError`-re fordít).
+ */
+export interface DyNTS_Mcp_ToolOutcome {
+    /** A strukturált eredmény-payload (a tool output-shape JSON-ja). */
+    data: unknown;
+    /** `true`, ha a kimenet strukturált hiba — az adaptor `isError`-re fordítja. */
+    isError?: boolean;
+}
+
+/**
+ * Egy tool-handler aláírása. Az `args` a nyers tool-argumentumok (JSON); a handler a saját
+ * input-shape-jére validál + a `DyNTS_Mcp_ToolOutcome`-ot adja. A hibát NEM nyeli el (strukturált
+ * hiba-payload `isError:true`-val VAGY dobott exception, amit az adaptor egységes MCP-error-ré fordít).
+ */
+export type DyNTS_Mcp_ToolHandler = (args: unknown) => Promise<DyNTS_Mcp_ToolOutcome>;
+
+/**
+ * Egy MCP tool-definíció (a `registerTool` egységes shape-je). A consumer ezt a shape-et használja az
+ * advertised halmazba (`name`+`description`+`inputSchema`+`handler`). A `tools/list` a regisztrált
+ * tool-ok `name`/`description`/`inputSchema`-ját hirdeti.
+ */
+export interface DyNTS_Mcp_ToolDefinition {
+    /** A tool neve (a `tools/list`-ben + a `tools/call` dispatch-kulcsa — UNIK kell legyen). */
+    name: string;
+    /** Agent-barát leírás (mikor melyik tool; az LLM ezt olvassa a tool-választáshoz). */
+    description: string;
+    /** A tool input JSON-schema-ja (a `tools/list` ezt hirdeti). */
+    inputSchema: DyNTS_Mcp_JsonSchema;
+    /** A handler (a transport-agnosztikus core-logika). */
+    handler: DyNTS_Mcp_ToolHandler;
+}
+
+/**
+ * Az MCP-szerver identitása (a SDK `serverInfo`-ja). A `name`/`version` a kliensnek hirdetett.
+ */
+export interface DyNTS_Mcp_ServerInfo {
+    /** A szerver neve (a kliensnek hirdetett `serverInfo.name`). */
+    name: string;
+    /** A szerver verziója (a kliensnek hirdetett `serverInfo.version`). */
+    version: string;
+}
+
+/**
+ * A támogatott transport-fajták. MVP: `stdio` (a JSON-RPC a stdin/stdout-on). A `start({transport})`
+ * ezzel választ — egy jövőbeli transport (pl. `http`/`sse`) NON-breaking módon bővíthető (csak az
+ * adaptor `start`-ja kap új ágat; a server-base + a tool-ok változatlanok).
+ */
+export type DyNTS_Mcp_TransportKind = 'stdio';
+
+/**
+ * A `start()` opciói. A `transport` választja a csatornát (default `stdio`).
+ */
+export interface DyNTS_Mcp_StartOptions {
+    /** A transport-csatorna (default `stdio`). */
+    transport?: DyNTS_Mcp_TransportKind;
+}
+
+/**
+ * Egy MCP `tools/call` strukturált eredménye (a transport-payload shape-je). Az adaptor ezt termeli;
+ * a `content` egy text-JSON blokk, az `isError` a strukturált-hiba jelzés. Ez a SDK
+ * `CallToolResult`-tal wire-kompatibilis al-shape (a SDK-t az adaptor izolálja, ezért itt a saját,
+ * SDK-független shape él).
+ */
+export interface DyNTS_Mcp_CallResult {
+    /** A tartalom-blokkok (MVP: egyetlen `text`-JSON blokk). */
+    content: { type: 'text'; text: string }[];
+    /** `true`, ha a hívás strukturált hibával végződött (no-silent-failure). */
+    isError?: boolean;
+}