lemon-core 4.3.0 → 5.0.1

package/dist/extended/cores/abstract-services.js

@@ -33,8 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.$ES6Routed = exports.$ES6 = exports.$OS2 = exports._OS2 = exports.OS2Instance = exports.OS2FGACManager = exports.OS2Service = exports.MyManagerProxy = exports.MyCoreProxy = exports.MyCoreManager = exports.MyCoreService = void 0;
-exports.sourceToItem = sourceToItem;
+exports.$ES6Routed = exports.$OS2 = exports._OS2 = exports.OS2Instance = exports.OS2FGACManager = exports.OS2Service = exports.MyManagerProxy = exports.MyCoreProxy = exports.MyCoreManager = exports.MyCoreService = exports.sourceToItem = void 0;
 /**
  * `abstract-services.ts`
  * - common services used in `/cores`
@@ -74,6 +73,8 @@ exports.sourceToItem = sourceToItem;
  * @date        2026-01-05 optimized `hasAdminRole()` and `getCurrentSession()`.
  * @date        2026-02-11 optimized `proxy.mget()` with `throwable` options.
  * @date        2026-04-09 optimized `types` to fix `ModelType` cast error.
+ * @date        2026-10-27 v5 B2-b: OpenSearch client, lazy `$OS2` (= `$ES6Routed`), one service set per instance.
+ * @date        2026-10-28 v5 B4: `CORE_FIELDS = fieldsOf(CoreModel)`; manager `fields` may be a model class.
  *
  * @copyright   (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
  * @origin      `@lemoncloud/lemon-templates-api/cores`
@@ -82,19 +83,24 @@ exports.sourceToItem = sourceToItem;
 const engine_1 = require("../../engine/");
 const cores_1 = __importStar(require("../../cores/"));
 const cores_2 = require("../../cores/");
-const cores_3 = require("../../cores/");
 const test_helper_1 = require("../../common/test-helper");
 const tools_1 = require("../../tools/");
 const helpers_1 = require("../../helpers/");
 const abstract_service_1 = require("../abstract-service");
+//* v5 B3: the local copy was identical to the L1 one (the root already used that); re-exported to keep this deep path.
+var abstract_service_2 = require("../abstract-service");
+Object.defineProperty(exports, "sourceToItem", { enumerable: true, get: function () { return abstract_service_2.sourceToItem; } });
+const lazy_1 = require("../../lib/lazy");
+const perf_1 = require("../../lib/perf");
+const lemon_model_1 = require("lemon-model");
 const commons_1 = require("./commons");
-const field_registry_1 = require("../../generated/field-registry");
 const NAME = engine_1.$U.env('NAME', 'lemon');
 const NS = engine_1.$U.NS('HDBS', 'green');
 /**
- * fields in core model.
+ * fields in core model (L2: the 14 L1 `CORE_FIELDS` + `id`, `_id`).
+ * - v5 B4: read from the `@field()` annotations of the `CoreModel` class (was the generated registry).
  */
-const CORE_FIELDS = field_registry_1.fieldKeys.coreModel();
+const CORE_FIELDS = (0, lemon_model_1.fieldsOf)(lemon_model_1.CoreModel);
 /**
  * lookup table for common types.
  */
@@ -120,9 +126,10 @@ class MyCoreService extends abstract_service_1.CoreService {
     }
     /**
      * make proxy, and use callback to handle.
-     * - it will save automatically.
+     * - it will save automatically on success.
+     * - v5: on exception it saves only when `options.saveOnError` is true (default false, B5 § 6.7).
      */
-    guardProxy = async (context, callback) => {
+    guardProxy = async (context, callback, options) => {
         const proxy = this.createProxy(context);
         try {
             const result = await callback(proxy);
@@ -131,20 +138,22 @@ class MyCoreService extends abstract_service_1.CoreService {
             return result;
         }
         catch (e) {
-            //WARN! force to save models even for exception @240613
-            const saved = await proxy.saveAllUpdates().catch(e => (0, test_helper_1.GETERR$)(e));
-            (0, engine_1._log)(`> saved =`, engine_1.$U.json(saved));
+            //* v5: save pending updates on exception only by opt-in (v4 always saved @240613).
+            if (options?.saveOnError) {
+                const saved = await proxy.saveAllUpdates().catch(e => (0, test_helper_1.GETERR$)(e));
+                (0, engine_1._log)(`> saved =`, engine_1.$U.json(saved));
+            }
             throw e;
         }
     };
     /**
-     * run search
-     * - override this to hide `$ES6`
+     * run search (via `$OS2`)
+     * - override this to hide `$OS2`
      */
     async doSearch(body) {
         (0, engine_1._log)(`doSearch()`);
         (0, engine_1._log)(`> list.query =`, engine_1.$U.json(body));
-        const result = await exports.$ES6.search(body);
+        const result = await exports.$OS2.search(body);
         (0, engine_1._log)(`> list.res =`, engine_1.$U.json({ ...result, list: [result?.list?.[0]] }));
         return result;
     }
@@ -155,18 +164,12 @@ class MyCoreService extends abstract_service_1.CoreService {
         const USE_SESSION = commons_1.$T.S(engine_1.$U.env('USE_SESSION', '')).toLowerCase();
         return USE_SESSION && USE_SESSION != '0' && USE_SESSION != 'false' ? true : false;
     }
-    /**
-     * @deprecated typo kept for 1 minor as a non-breaking alias — use `isUseSession()` instead. (cores-migration P1, decision #2)
-     */
-    isUseSssion() {
-        return this.isUseSession();
-    }
     /**
      * check if search-engine is supportable
      * @returns
      */
     hasSearchEngine() {
-        const useSearch = !!exports.$ES6.options?.indexName;
+        const useSearch = !!exports.$OS2.options?.indexName;
         return useSearch;
     }
 }
@@ -187,12 +190,16 @@ class MyCoreManager extends abstract_service_1.CoreManager {
      * constructor
      * @protected
      */
-    constructor(type, parent, fields, options) {
+    constructor(type, parent, 
+    //* v5 B4: a `string[]` or a model class (resolved in `AbstractManager`).
+    fields, options) {
         super(type, parent, fields, options?.uniqueField);
         this.options = options;
-        const enableSync = options?.enableSync ?? true;
+        //* v5: sync is opt-in (default false), so `$OS2` is built only when a manager asks (B5 § 6.7).
+        const enableSync = options?.enableSync ?? false;
+        //* the first manager with `enableSync: true` builds the lazy `$OS2` (1 listener when `OS2_ENDPOINT` is set).
         if (enableSync)
-            exports.$ES6.synchronizer?.enableSynchronization(this.type);
+            exports.$OS2.synchronizer?.enableSynchronization(this.type);
         this.logNS = engine_1.$U.NS(type, 'yellow');
     }
     /**
@@ -690,11 +697,12 @@ class MyCoreManager extends abstract_service_1.CoreManager {
             return result;
         };
         const _saveBulk = async (operations) => {
-            const elastic = exports.$ES6.client;
+            const elastic = exports.$OS2.client;
             const $res = await elastic.bulk({ body: operations }).catch(e => {
                 (0, engine_1._err)(this.NS, `>> err=`, e);
                 throw e;
             });
+            //* the OS client types `items[].index.error` as an object; read it in the v4 shape.
             const list = $res.body?.items?.map(item => ({
                 _id: item.index._id,
                 _version: item.index._version,
@@ -714,7 +722,7 @@ class MyCoreManager extends abstract_service_1.CoreManager {
         const _transformBulkOperations = (dataChunk) => {
             return dataChunk.flatMap(doc => {
                 const { _id, ...items } = doc;
-                return [{ index: { _index: exports.$ES6.options?.indexName, _id: doc._id } }, items];
+                return [{ index: { _index: exports.$OS2.options?.indexName, _id: doc._id } }, items];
             });
         };
         const results = await (0, helpers_1.my_sequence)(chunkList, async (N) => {
@@ -821,7 +829,8 @@ class MyCoreProxy extends abstract_service_1.AbstractProxy {
         USE_SESSION && (0, engine_1._inf)(this.service.NS, `> use-session =`, useSession, USE_SESSION);
         const context = (options?.context ?? this.context);
         //* WARN - in case of local, no need to throw error.
-        const isLocal = context?.domain === 'localhost';
+        //* v5: local mode is a runtime setting (`LOCAL_MODE=1` off Lambda), never from `context.domain` (B5 § 6.3).
+        const isLocal = engine_1.$U.isLocalMode();
         // load the `identity-token` from json file.
         const _load = (file) => {
             const data = (0, tools_1.loadJsonSync)(file);
@@ -856,12 +865,14 @@ class MyCoreProxy extends abstract_service_1.AbstractProxy {
                 }
             }
             //TODO - 아래 코드는 개선의 여지가 있음(문제점???) @241210
-            if (LOCAL_ACCOUNT)
+            //* v5: `LOCAL_ACCOUNT` is honoured only in local mode (B5 § 6.3).
+            if (LOCAL_ACCOUNT && isLocal)
                 return _default();
             if (useSession) {
                 // _inf(this.service.NS, `> use-session =`, useSession, USE_SESSION);
                 if (useSession === true || useSession === 'true' || useSession === '1') {
-                    if (USE_SESSION?.endsWith('.json')) {
+                    //* v5: a session file (`USE_SESSION=*.json`) is honoured only in local mode (B5 § 6.3).
+                    if (isLocal && USE_SESSION?.endsWith('.json')) {
                         const $sess = _load(USE_SESSION);
                         (0, engine_1._inf)(this.service.NS, `> use-session-json =`, engine_1.$U.json($sess));
                         return $sess;
@@ -906,7 +917,8 @@ class MyCoreProxy extends abstract_service_1.AbstractProxy {
      */
     asCurrentIdentityId = (context) => {
         context = context ?? this.context;
-        if (context?.domain === 'localhost' && !context?.identity?.identityId) {
+        //* v5: `LOCAL_ACCOUNT` fallback only in local mode, not from `context.domain` (B5 § 6.3).
+        if (engine_1.$U.isLocalMode() && !context?.identity?.identityId) {
             const LOCAL_ACCOUNT = engine_1.$U.env('LOCAL_ACCOUNT', '');
             return LOCAL_ACCOUNT ? LOCAL_ACCOUNT : null;
         }
@@ -923,8 +935,8 @@ class MyCoreProxy extends abstract_service_1.AbstractProxy {
         const errScope = options?.errScope ?? `assertContext()`;
         const $idt = context?.identity;
         const isS = (s) => typeof s === 'string' && s?.length > 0;
-        //* call in local
-        const isLocal = context?.domain === 'localhost';
+        //* call in local (v5: runtime local mode only, never from `context.domain` — B5 § 6.3)
+        const isLocal = engine_1.$U.isLocalMode();
         //* signed call with access-key
         const isSigned = isS($idt?.accessKey);
         //* authed by cognito provider.
@@ -959,7 +971,7 @@ class MyCoreProxy extends abstract_service_1.AbstractProxy {
     }
     /**
      * check if current context has `admin` access
-     * 1. run in local environ (or internal protocol with domin='localhost')
+     * 1. run in local mode (`$U.isLocalMode()`, v5 — no longer `domain='localhost'`)
      * 2. access via signed access-key
      * 3. authorized cognito and has `admin` role in identity-token.
      *
@@ -1086,12 +1098,11 @@ class MyManagerProxy extends abstract_service_1.ManagerProxy {
      * @returns
      */
     packSearchParam(param, model, options) {
-        const $ctx = this.proxy.context;
         const type = this.$mgr.type;
         const useSession = options?.useSession ?? false;
         const throwable = options?.throwable ?? true;
         const errScope = options?.errScope ?? `packSearchParam(${type})`;
-        const isLocal = $ctx?.domain === 'localhost';
+        const isLocal = engine_1.$U.isLocalMode(); //* v5: drop the `sid` pin only in local mode (B5 § 6.3).
         const session = useSession ? this.proxy.getCurrentSession({ throwable }) : null;
         const _has = (name) => param && (typeof param[name] === 'string' || typeof param[name] === 'number');
         const _val = (name) => (param ? commons_1.$T.S2(param[name]) : undefined);
@@ -1221,14 +1232,23 @@ class MyManagerProxy extends abstract_service_1.ManagerProxy {
         const $sess = this.proxy.getCurrentSession({ throwable, useSession, context });
         if (useSession && !$sess)
             return false;
+        // session & model information.
+        const S = { sid: commons_1.$T.S2($sess?.sid), uid: commons_1.$T.S2($sess?.uid) };
+        const M = { sid: commons_1.$T.S2(model?.sid), uid: commons_1.$T.S2(model?.uid) };
+        //* v5: access mode for update/delete of a `sid`-less record, env `SID_LEGACY_ACCESS` (B5 § 6.4).
+        const legacy = engine_1.$U.sidLegacyAccess();
+        const isLegacyWrite = !M.sid && (_act === 'update' || _act === 'delete');
+        //* v5: `deny` refuses update/delete of a `sid`-less record before the admin pass (B5 § 6.4).
+        if (isLegacyWrite && legacy === 'deny') {
+            if (throwable)
+                throw new Error(`403 NOT ALLOWED - action[${_act}] is invalid @${errScope}`);
+            return false;
+        }
         // admin can do anything.
         const isAdmin = this.proxy.hasAdminRole(null, { errScope, context });
         const hasRole = $sess?.roles?.length > 0 ? true : false; // guest if empty.
         if (isAdmin)
             return true;
-        // session & model information.
-        const S = { sid: commons_1.$T.S2($sess?.sid), uid: commons_1.$T.S2($sess?.uid) };
-        const M = { sid: commons_1.$T.S2(model?.sid), uid: commons_1.$T.S2(model?.uid) };
         // check action.
         if (hasRole) {
             switch (_act) {
@@ -1243,9 +1263,13 @@ class MyManagerProxy extends abstract_service_1.ManagerProxy {
                     break;
                 case 'update':
                 case 'delete':
-                    // (default) action is allowed if sid&uid matches or no sid.
-                    if (!M.sid)
-                        return true;
+                    // (default) action is allowed if sid&uid matches.
+                    //* v5: a `sid`-less record is admin-only for update/delete (B5 § 6.4); `open` keeps the v4 rule.
+                    if (!M.sid) {
+                        if (legacy === 'open')
+                            return true;
+                        break;
+                    }
                     if (S.sid === M.sid && S.uid === M.uid)
                         return true;
                     break;
@@ -1351,112 +1375,29 @@ exports.MyManagerProxy = MyManagerProxy;
 /**
  * class: `OS2Service`
  * - Master 권한 전용 Elasticsearch 관리 서비스
- * - elasticsearch service for OS2.
+ * - service for OS2: data path via FGAC (`$fgac`), index management via the master client.
  */
-class OS2Service extends cores_1.Elastic6Service {
+class OS2Service extends cores_1.OS2CoreService {
     $fgac;
-    static instance(endpoint) {
-        const _config = (n) => cores_1.default.config.config.get(n);
-        const masterUser = _config('OS2_MASTER_UID');
-        const masterPass = _config('OS2_MASTER_PWD');
-        // if (!masterUser || !masterPass) throw new Error('400 NO MASTER - OS2_MASTER_UID/OS2_MASTER_PWD is required!');
-        const client = new cores_3.elasticsearch.Client({
-            node: endpoint,
-            ssl: {
-                ca: process.env.elasticsearch_certificate,
-                rejectUnauthorized: false,
-            },
-            auth: {
-                username: masterUser,
-                password: masterPass,
-            },
-        });
-        return { client };
-    }
+    /**
+     * constructor (no client here; the master client is created on first `client` access)
+     */
     constructor(options, fgac) {
         super(options);
-        if (!options.endpoint)
-            throw new Error('.endpoint (URL) is required');
-        if (!options.indexName)
-            throw new Error('.indexName (string) is required');
-        const { client } = OS2Service.instance(options.endpoint);
-        this._options = { docType: '_doc', idName: '$id', version: '6.8', ...options };
-        this._client = client;
         this.$fgac = fgac;
     }
-    get client() {
-        return this._client;
-    }
-    get options() {
-        return this._options;
-    }
-    /**
-     * describe `settings` and `mappings` of index.
-     */
-    async describe() {
-        const { indexName } = this.options;
-        //* call create index..
-        (0, engine_1._log)(NS, `- describe(${indexName})`);
-        //* read settings.
-        // const { client } = instance(endpoint);
-        const client = this.client;
-        const res = await client.indices.getSettings({ index: indexName }).catch(
-        // $ERROR.throwAsJson,
-        cores_1.$ERROR.handler('describe', e => {
-            const msg = (0, test_helper_1.GETERR)(e);
-            if (msg.startsWith('404 INDEX NOT FOUND'))
-                throw new Error(`404 NOT FOUND - index:${indexName}`);
-            throw e;
-        }));
-        (0, engine_1._log)(NS, `> settings[${indexName}] =`, engine_1.$U.json({ ...res, meta: undefined }));
-        const settings = (res.body && res.body[indexName] && res.body[indexName].settings) || {};
-        (0, engine_1._log)(NS, `> number_of_shards =`, settings.index && settings.index.number_of_shards); // 5
-        (0, engine_1._log)(NS, `> number_of_replicas =`, settings.index && settings.index.number_of_replicas); // 1
-        //* read mappings.
-        const res2 = await client.indices.getMapping({ index: indexName });
-        (0, engine_1._log)(NS, `> mappings[${indexName}] =`, engine_1.$U.json(res2));
-        const mappings = (res2.body && res2.body[indexName] && res2.body[indexName].mappings) || {};
-        //* returns
-        return { settings, mappings };
-    }
     /**
-     * create index by name
-     * @param settings - creating settings
+     * build the master client: `auth` is read from config now (after engine init), and set only when both exist.
      */
-    async createIndex(settings) {
-        const { indexName, docType, idName, timeSeries, version } = this.options;
-        settings = settings || cores_1.Elastic6Service.prepareSettings({ docType, idName, timeSeries, version });
-        if (!indexName)
-            new Error('@index is required!');
-        (0, engine_1._log)(NS, `- createIndex(${indexName})`);
-        //* prepare payload
-        const payload = {
-            settings: {
-                number_of_shards: 5,
-                number_of_replicas: 1,
-            },
-            ...settings,
-        };
-        (0, engine_1._log)(NS, `> settings[${indexName}] = `, engine_1.$U.json(payload));
-        //* call create index..
-        const client = this.client;
-        const res = await client.indices.create({ index: indexName, body: payload }).catch(
-        // $ERROR.throwAsJson,
-        cores_1.$ERROR.handler('create', e => {
-            const msg = (0, test_helper_1.GETERR)(e);
-            if (msg.startsWith('400 RESOURCE ALREADY EXISTS'))
-                throw new Error(`400 IN USE - index:${indexName}`);
-            throw e;
-        }));
-        // if (res) throw res;
-        (0, engine_1._log)(NS, `> create[${indexName}] =`, engine_1.$U.json({ ...res, meta: undefined }));
-        //* build result.
-        return {
-            status: res.statusCode,
-            index: indexName,
-            acknowledged: res.body.shards_acknowledged,
-        };
+    createClient() {
+        const _config = (n) => cores_1.default.config.config.get(n);
+        const username = _config('OS2_MASTER_UID');
+        const password = _config('OS2_MASTER_PWD');
+        const auth = username && password ? { auth: { username, password } } : {};
+        //* same node/ssl as the base; the package is loaded here, on first use.
+        return this.newClient(auth);
     }
+    //* v5 B3: `describe`/`createIndex`/`search` are inherited from `OS2CoreService` (identical-body overrides removed).
     /**
      * delete index by name
      */
@@ -1512,7 +1453,7 @@ class OS2Service extends cores_1.Elastic6Service {
     async bulkItems(items, options) {
         const errScope = `bulkItems(${this.options.indexName})`;
         const { indexName } = this.options;
-        const client = this.client;
+        //* FGAC only: do not touch `this.client` here (it would create the master client).
         const idName = options?.idName ?? '_id';
         if (!Array.isArray(items) || items.length === 0)
             throw new Error(`@items (array) is required - length=${items?.length ?? 'null'} - ${errScope}`);
@@ -1562,19 +1503,17 @@ class OS2Service extends cores_1.Elastic6Service {
         return { success, failed, failedItems };
     }
     /**
-     * push item for time-series data.
+     * push item for time-series data (via FGAC; the result is the response body itself).
      *
      * @param item - item to push
-     * @param type - document type (default: doc-type given at construction time)
      */
-    async pushItem(item, type) {
-        const { indexName, docType } = this.options;
+    async pushItem(item) {
+        const { indexName } = this.options;
         const id = item.id ?? '';
-        type = `${type || docType}`;
         const body = { ...item };
         const body2 = this.popullateAutocompleteFields(body);
         (0, engine_1._log)(NS, `- pushItem(${id})`);
-        const params = { index: indexName, type, body: body2, id };
+        const params = { index: indexName, body: body2, id };
         (0, engine_1._log)(NS, `> params[${id}] =`, engine_1.$U.json(params));
         //NOTE - use npm `elasticsearch#13.2.0` for avoiding error.
         // const { client } = instance(endpoint);
@@ -1586,8 +1525,9 @@ class OS2Service extends cores_1.Elastic6Service {
         }));
         // {"_index":"test-v3","_type":"_doc","_id":"rTeHiW4BPb_liACrA9qa","_version":1,"result":"created","_shards":{"total":2,"successful":2,"failed":0},"_seq_no":2,"_primary_term":1}
         (0, engine_1._log)(NS, `> create[${id}].res =`, engine_1.$U.json({ ...res, meta: undefined }));
-        const _id = res.body?._id;
-        const _version = res.body?._version;
+        //* fixed: the FGAC result is the body itself (v4 read `res.body?._id`, always undefined)
+        const _id = res?._id;
+        const _version = res?._version;
         const res2 = { ...body, _id, _version };
         return res2;
     }
@@ -1598,10 +1538,9 @@ class OS2Service extends cores_1.Elastic6Service {
      * @param views - projections
      */
     async readItem(id, views) {
-        const { indexName, docType } = this.options;
-        const type = `${docType}`;
+        const { indexName } = this.options;
         (0, engine_1._log)(NS, `- readItem(${id})`);
-        const params = { index: indexName, type, id };
+        const params = { index: indexName, id };
         if (views) {
             const fields = [];
             const keys = Array.isArray(views) ? views : Object.keys(views);
@@ -1627,8 +1566,8 @@ class OS2Service extends cores_1.Elastic6Service {
         const _version = res._version;
         const data = res?._source || res._source || {};
         // delete internal (analyzed) field
-        delete data[cores_1.Elastic6Service.DECOMPOSED_FIELD];
-        delete data[cores_1.Elastic6Service.QWERTY_FIELD];
+        delete data[cores_1.OS2CoreService.DECOMPOSED_FIELD];
+        delete data[cores_1.OS2CoreService.QWERTY_FIELD];
         const res2 = { ...data, _id, _version };
         return res2;
     }
@@ -1638,10 +1577,9 @@ class OS2Service extends cores_1.Elastic6Service {
      * @param id - item-id
      */
     async deleteItem(id) {
-        const { indexName, docType } = this.options;
-        const type = `${docType}`;
+        const { indexName } = this.options;
         (0, engine_1._log)(NS, `- deleteItem(${id})`);
-        const params = { index: indexName, type, id, body: {} };
+        const params = { index: indexName, id, body: {} };
         (0, engine_1._log)(NS, `> params[${id}] =`, engine_1.$U.json(params));
         // const { client } = instance(endpoint);
         const res = await this.$fgac.doFgacDelete(params).catch(cores_1.$ERROR.handler('delete', e => {
@@ -1688,13 +1626,13 @@ class OS2Service extends cores_1.Elastic6Service {
     async searchRaw(body, searchType) {
         if (!body)
             throw new Error('@body (SearchBody) is required');
-        const { indexName, docType } = this.options;
+        const { indexName } = this.options;
         (0, engine_1._log)(NS, `- search(${indexName}, ${searchType || ''})....`);
         (0, engine_1._log)(NS, `> body =`, engine_1.$U.json(body));
-        const tmp = docType ? docType : '';
-        const params = { index: indexName, body, searchType };
-        // check version to include 'type' in params
-        (0, engine_1._log)(NS, `> params[${tmp}] =`, engine_1.$U.json({ ...params, body: undefined }));
+        const params = { index: indexName, body };
+        if (searchType)
+            params.search_type = searchType;
+        (0, engine_1._log)(NS, `> params =`, engine_1.$U.json({ ...params, body: undefined }));
         const $res = await this.$fgac.doFgacSearch(params).catch(cores_1.$ERROR.handler('search', e => {
             (0, engine_1._err)(NS, `> search[${indexName}].err =`, e);
             throw e;
@@ -1702,31 +1640,6 @@ class OS2Service extends cores_1.Elastic6Service {
         //* return raw results.
         return $res;
     }
-    /**
-     * run search, and get the formatmted response.
-     * @param body - Elasticsearch Query DSL that defines the search request (e.g., size, query, filters).
-     * @param searchType - type of search (e.g., 'query_then_fetch', 'dfs_query_then_fetch').
-     *
-     */
-    async search(body, searchType) {
-        const size = engine_1.$U.N(body.size, 0);
-        const response = await this.searchRaw(body, searchType);
-        // return w/ transformed id
-        const hits = response.hits;
-        if (typeof hits !== 'object')
-            throw new Error(`.hits (object) is required - hits:${engine_1.$U.json(hits)}`);
-        //NOTE - ES6.8 w/ OS1.1
-        return {
-            total: typeof hits.total?.value === 'number' ? hits.total?.value : hits.total,
-            list: hits.hits.map((hit) => ({
-                ...hit._source,
-                _id: hit._id,
-                _score: hit._score,
-            })),
-            last: hits.hits.length === size && size > 0 ? hits.hits[size - 1]?.sort : undefined,
-            aggregations: response.aggregations,
-        };
-    }
 }
 exports.OS2Service = OS2Service;
 /**
@@ -1770,7 +1683,7 @@ class OS2FGACManager {
     async doFgacSearch(params) {
         const index = params?.index ?? '';
         const body = (0, commons_1.onlyDefined)(params?.body ?? undefined);
-        const queryParams = params?.searchType ? { search_type: params?.searchType } : undefined;
+        const queryParams = params?.search_type ? { search_type: params?.search_type } : undefined;
         return this.proxy.doProxy('POST', index, `_search`, queryParams, body);
     }
     /** FGAC 기반 읽기: client.get() 대응 */
@@ -1901,31 +1814,33 @@ exports.OS2FGACManager = OS2FGACManager;
 /**
  * OS2 인스턴스
  * - describeIndex(), destroyIndex(), search() with elastic initialized by master-key
+ * - one service set (fgac, elastic, query, synchronizer) only when `endpoint && indexName`.
  */
-class OS2Instance extends abstract_service_1.Elastic6Instance {
+class OS2Instance extends abstract_service_1.AbstractOS2Instance {
     fgac;
-    constructor({ endpoint, indexName, idName, esVersion, esDocType, tableName, autocompleteFields, roleName, userName, }) {
-        super({ endpoint, indexName, esVersion, esDocType, tableName, autocompleteFields });
+    /**
+     * build one service set when `endpoint && indexName` (no client: it is created on first use).
+     */
+    constructor({ endpoint, indexName, idName, tableName, autocompleteFields, roleName, userName, }) {
+        super();
         const options = (0, commons_1.onlyDefined)({
             endpoint,
             indexName,
-            version: esVersion,
             autocompleteFields,
             roleName,
             userName,
             idName: idName === null ? undefined : idName ?? '$id',
         });
         if (endpoint && indexName) {
-            if (esDocType)
-                options.docType = esDocType;
             this.fgac = new OS2FGACManager(options);
             this.elastic = new OS2Service(options, this.fgac);
-            this.client = this.elastic.client;
-            this.query = new cores_1.Elastic6QueryService(this.elastic);
-            this.synchronizer = new abstract_service_1.Elastic6Synchronizer(this.elastic, { tableName });
+            this.query = new cores_1.OS2QueryService(this.elastic);
+            this.synchronizer = new abstract_service_1.OS2Synchronizer(this.elastic, { tableName });
         }
     }
     hello = () => `OS2Instance`;
+    //* v5 B3: `describeIndex` is inherited from `AbstractOS2Instance` (identical-body override removed).
+    //* kept (unlike the removed identical overrides): it narrows the return type to `OS2Option`.
     get options() {
         if (!this.elastic)
             return null;
@@ -1934,35 +1849,6 @@ class OS2Instance extends abstract_service_1.Elastic6Instance {
     get $X2() {
         return $X2;
     }
-    /**
-     * display index settings and mappings
-     */
-    async describeIndex() {
-        return this.elastic && (await this.elastic.describe());
-    }
-    /**
-     * create Elasticsearch index with ES7+ mapping structure
-     */
-    async createIndex() {
-        if (!this.elastic)
-            return null;
-        const { docType, idName, version = '2.10' } = this.options;
-        const settings = cores_1.Elastic6Service.prepareSettings({ docType, idName, version });
-        // _doc 제거 및 properties 병합
-        if (settings.mappings?._doc) {
-            const { dynamic_templates, properties: docProperties } = settings.mappings._doc;
-            settings.mappings = {
-                ...settings.mappings,
-                ...(dynamic_templates ? { dynamic_templates } : {}),
-                properties: {
-                    ...(docProperties || {}),
-                    ...(settings.mappings.properties || {}),
-                },
-            };
-            delete settings.mappings._doc;
-        }
-        return this.elastic.createIndex(settings);
-    }
     /**
      * search
      */
@@ -2074,14 +1960,6 @@ class OS2Instance extends abstract_service_1.Elastic6Instance {
     }
 }
 exports.OS2Instance = OS2Instance;
-function sourceToItem(_source, idName = '$id') {
-    const item = { ..._source };
-    if (idName in item) {
-        item._id = item[idName];
-        delete item[idName];
-    }
-    return item;
-}
 /**
  * internal tools
  */
@@ -2132,25 +2010,21 @@ const $X2 = {
 };
 /**
  * factory of `OS2Instance`
+ * - reads `OS2_ENDPOINT`, `OS2_INDEX`, `MY_DYNAMO_TABLE`, `OS2_AUTOCOMPLETE_FIELDS` (no version, no doc-type).
  */
 const _OS2 = (options) => {
     return new (class extends OS2Instance {
+        // 0. load from env configuration, then 1. build the instance.
         constructor() {
-            // 0. load from env configuration.
             const endpoint = options?.endpoint ?? engine_1.$U.env('OS2_ENDPOINT', '');
             const indexName = options?.indexName ?? engine_1.$U.env('OS2_INDEX', 'test-x1');
-            const esVersion = options?.version ?? engine_1.$U.env('OS2_VERSION', '2.10');
-            const esDocType = options?.docType ?? engine_1.$U.env('OS2_DOCTYPE', '');
             const tableName = engine_1.$U.env('MY_DYNAMO_TABLE', '');
             const autocompleteFields = options?.autocompleteFields ?? commons_1.$T.SS(engine_1.$U.env('OS2_AUTOCOMPLETE_FIELDS', ''));
             const roleName = options?.roleName;
             const userName = options?.userName;
-            // 1. initialize instance.
             super({
                 endpoint,
                 indexName,
-                esVersion,
-                esDocType,
                 tableName,
                 autocompleteFields,
                 roleName,
@@ -2166,16 +2040,15 @@ const _OS2 = (options) => {
     })();
 };
 exports._OS2 = _OS2;
-/** dynamically load the OS2 instance if `OS2_ENDPOINT` is set */
-const hasOS2 = engine_1.$U.env('OS2_ENDPOINT', '').startsWith('https://');
-exports.$OS2 = (0, exports._OS2)();
-exports.$ES6 = hasOS2 ? (0, exports._OS2)() : (0, abstract_service_1._ES6)();
 /**
- * explicit alias for the OS2-routing `$ES6` above (decision #3, cores-migration P1).
- * - kept as `$ES6` here for deep-import compatibility (`lemon-core/dist/extended/cores`).
- * - exported at root ONLY under this name: root `$ES6` stays pinned to the L1
- *   (non-OS2) `extended/abstract-service` version, so consumers must opt in by
- *   name instead of silently getting OS2-routing behavior via the root barrel.
+ * the default `OS2Instance`, built lazily by `_OS2()` on first access (S-25).
+ * - nothing is built at import: no client, no dynamo-stream listener.
+ * - without `OS2_ENDPOINT` it is an `OS2Instance` with `options === null`.
+ */
+//* the factory prints one `PERF > instance $OS2` line (D40; the namespace is built at call time).
+exports.$OS2 = (0, lazy_1.lazyInstance)(() => (0, perf_1.measure)(engine_1._inf, engine_1.$U.NS('PERF', 'cyan'), 'instance $OS2', () => (0, exports._OS2)()));
+/**
+ * explicit alias of `$OS2` (the same object). The name is kept; the meaning is OS2.
  */
-exports.$ES6Routed = exports.$ES6;
+exports.$ES6Routed = exports.$OS2;
 //# sourceMappingURL=abstract-services.js.map