lemon-core 4.2.7 → 5.0.0

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

@@ -0,0 +1,2042 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+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`
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-06-15 initial version
+ * @date        2022-06-24 fixed some failures.
+ * @date        2022-07-27 support { initialNo, throwable }
+ * @date        2022-08-04 opt `list()` w/ sort by createdAt:desc
+ * @date        2022-08-09 use `SessionToken` from context
+ * @date        2022-11-04 filter of `not exists` if param==''
+ * @date        2022-11-15 use `buildQuery()` to build search-body.
+ * @date        2022-12-29 optimized with `lemon-core@3.2.1`
+ * @date        2023-01-13 optimized `makeModel()`
+ * @date        2023-01-18 optimized with `lemon-core@3.2.4`
+ * @date        2023-01-20 optimized `doSearch()` w/ `SearchParam()`
+ * @date        2023-01-31 fixed null error of `model[key]`
+ * @date        2023-02-15 optimized with `lemon-core@3.2.5`
+ * @date        2023-09-15 optimized `getCurrentSession()` w/ USE_SESSION + normalize option.
+ * @date        2023-10-08 optimized `buildQuery()` w/ sort + offset.
+ * @date        2023-10-11 optimized `doScan()` w/ dynamo-scan-filter.
+ * @date        2024-11-01 optimized `nextId()` of manager-proxy
+ * @date        2023-11-06 optimized `onAfterSave()` for post-processing.
+ * @date        2024-11-14 renamed to `IdentityToken` from `SessionToken`
+ * @date        2024-11-28 optimized `assertContext()` and `isAdminRole()` w/ `lemon-core@3.2.11`.
+ * @date        2025-01-03 optimized `buildQuery()` w/ sort + offset.
+ * @date        2025-03-24 optimized `OS2Instance` with `lemon-core@3.2.13`
+ * @date        2025-07-17 optimized `onAfterSave` with `lemon-core@4.0.4`
+ * @date        2025-07-23 optimized `buildQuery()` with `hidden` + `aggregation` option.
+ * @date        2025-08-01 optimized `canDo()` for better security w/ session.
+ * @date        2025-08-11 optimized `OS2FGACManager` for latest features.
+ * @date        2025-08-14 optimized `OS2.deleteIndex()` for latest features.
+ * @date        2025-09-05 optimized `OS2FGACManager` environment variables.
+ * @date        2025-10-31 optimized `session` with `lemon-devkit@0.0.8`.
+ * @date        2025-12-01 optimized `makeModel()` w/ T.
+ * @date        2025-12-15 optimized `getCurrentSession()` with local meta info.
+ * @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`
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const engine_1 = require("../../engine/");
+const cores_1 = __importStar(require("../../cores/"));
+const cores_2 = 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 NAME = engine_1.$U.env('NAME', 'lemon');
+const NS = engine_1.$U.NS('HDBS', 'green');
+/**
+ * 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 = (0, lemon_model_1.fieldsOf)(lemon_model_1.CoreModel);
+/**
+ * lookup table for common types.
+ */
+const $LUT = {
+    /**
+     * type: `CanDoAction`
+     */
+    CanDoAction: {
+        list: 'list',
+        read: 'read',
+        create: 'create',
+        update: 'update',
+        delete: 'delete',
+    },
+};
+/**
+ * class: `MyCoreService`
+ * - CoreService의 공통 부분을 채워넣는다.
+ */
+class MyCoreService extends abstract_service_1.CoreService {
+    constructor(tableName, ns) {
+        super(tableName, ns);
+    }
+    /**
+     * make proxy, and use callback to handle.
+     * - 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, options) => {
+        const proxy = this.createProxy(context);
+        try {
+            const result = await callback(proxy);
+            const saved = await proxy.saveAllUpdates();
+            (0, engine_1._log)(`> saved[${saved?.length}] =`, engine_1.$U.json(saved));
+            return result;
+        }
+        catch (e) {
+            //* 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 (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.$OS2.search(body);
+        (0, engine_1._log)(`> list.res =`, engine_1.$U.json({ ...result, list: [result?.list?.[0]] }));
+        return result;
+    }
+    /**
+     * check if using useSession from environ.
+     */
+    isUseSession() {
+        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;
+    }
+    /**
+     * check if search-engine is supportable
+     * @returns
+     */
+    hasSearchEngine() {
+        const useSearch = !!exports.$OS2.options?.indexName;
+        return useSearch;
+    }
+}
+exports.MyCoreService = MyCoreService;
+/**
+ * class: `CoreManager`
+ * - shared core manager for all model
+ *
+ * @abstract
+ */
+class MyCoreManager extends abstract_service_1.CoreManager {
+    options;
+    /**
+     * namespace for log(print)
+     */
+    logNS;
+    /**
+     * constructor
+     * @protected
+     */
+    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;
+        //* 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.$OS2.synchronizer?.enableSynchronization(this.type);
+        this.logNS = engine_1.$U.NS(type, 'yellow');
+    }
+    /**
+     * get the next sequenced no from `initialNo` (default 1000000)
+     *
+     * @param step (optional) next-step (>= 0)
+     * @returns next seq-no
+     */
+    async nextId(step) {
+        return this.storage.storage.nextSeq(this.storage.type, this.options?.initialNo, step);
+    }
+    /**
+     * build default model for creation.
+     */
+    buildDefault(id) {
+        //WARN! do not include { last, balance } (avoid conflict)
+        const $def = this.prepareDefault({ id });
+        const $key = this.parent.asKey$(this.type, id);
+        return (0, commons_1.onlyDefined)({ ...$def, ...$key, _id: undefined });
+    }
+    /**
+     * validate the request's model before saving.
+     * - `$org`에 따라서, 신규 생성인지 업데이트인지 구분 가능함.
+     *
+     * @param model request's model
+     * @param $org (optional) the origin model (valid ONLY if 업데이트)
+     * @returns validatated model.
+     */
+    async validateModel(model, $org) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const isCreate = !$org; // flag to indicate new creation.
+        return model;
+    }
+    /**
+     * find lookup-model (improved @2022)
+     * - lookup to `auto-id` by key.
+     * - if not exits, make the new id (auto-seq) and store the key.
+     * - type should be like `#<type>`.
+     *
+     * NOTE! must to support race condition.
+     *
+     * @param key any string
+     */
+    async findLookup$(key, params) {
+        //! valida parameters...
+        const resetRate = params?.resetRate ?? 0.9; // upper rate to reset lock
+        const useSha256 = params?.useSha256 ?? true; // flag to use sha256 algorithm.
+        const isUseMeta = params?.isUseMeta ?? false; // flag to use meta
+        //! build hash...
+        const text = typeof key === 'number' ? `${key}` : `${key || ''}`;
+        const hash = useSha256 ? engine_1.$U.md5(text, 'base64') : engine_1.$U.hash(text);
+        const keyId = `#${hash}.${text.length}`;
+        //! recursive func to repeat
+        const asyncAuto = async ($base, depth = 0) => {
+            const keyId = $base.id;
+            //NOTE - it will throw if no lookup exists.
+            const $org = await this.storage.read(keyId).catch(e => {
+                if (params?.throwable)
+                    throw e;
+                return (0, test_helper_1.NUL404)(e);
+            });
+            //! try to initialize the lookup key.......
+            if (!$org || !$org?.next) {
+                const $inc = { lock: 1 };
+                const $ups = { stereo: $base.stereo, meta: $base.meta };
+                const $lock = await this.storage.increment(keyId, $inc, $ups);
+                if ($lock.lock === 1) {
+                    // const nextId = await this.storage.storage.nextSeq(this.storage.type, params?.initialNo);
+                    const nextId = await this.nextId();
+                    const $ups = {
+                        id: keyId,
+                        type: `#${this.type}`,
+                        next: nextId,
+                        createdAt: $lock.createdAt ?? $lock.updatedAt,
+                        deletedAt: 0,
+                    };
+                    const $updated = await this.storage.update(keyId, $ups);
+                    return { ...$lock, ...$updated };
+                }
+                else if (depth > 100) {
+                    throw new Error(`@depth[${depth}] is out of range - findLookup(${$base?.meta?.text})`);
+                }
+                //! in some rate, try to reset lock.
+                const rate = Math.random();
+                const wait = Math.round(rate * 10);
+                return (0, test_helper_1.waited)(wait)
+                    .then(() => (rate > resetRate ? this.storage.update(keyId, { lock: 0 }) : null))
+                    .then(() => asyncAuto($base, depth + 1));
+            }
+            return $org;
+        };
+        //! make base model, and start loop.
+        const meta = isUseMeta ? { hash, text } : undefined;
+        const stereo = isUseMeta ? '#' : `#${text}`;
+        return asyncAuto({ id: keyId, meta, stereo });
+    }
+    /**
+     * build search query from filters
+     */
+    buildQuery(param, model, options) {
+        const errScope = options?.errScope ?? `buildQuery(${this.type})`;
+        if (typeof param?.limit !== 'number')
+            throw new Error(`.limit(number) is required - ${errScope}`);
+        if (param?.page && typeof param?.page !== 'number')
+            throw new Error(`.page(number) is required - ${errScope}`);
+        if (param?.offset && typeof param?.offset !== 'number')
+            throw new Error(`.offset(number) is required - ${errScope}`);
+        const aggregation = options?.aggregation ?? 'stereo'; // default aggregation
+        const aggrLimit = options?.aggrLimit ?? 12; // default aggregation limit
+        // STEP.0 validate parameters.
+        const { limit } = param;
+        const page = commons_1.$T.N(param?.page, 0);
+        const offset = commons_1.$T.N(param?.offset, 0);
+        // 1. build search request body
+        const body = {
+            size: limit,
+            from: limit * page + offset,
+            query: {
+                bool: {
+                    filter: [
+                        { term: { 'ns.keyword': this.parent.NS } },
+                        { term: { 'type.keyword': this.type } },
+                        { term: { deletedAt: 0 } },
+                    ],
+                },
+            },
+        };
+        //* apply aggregation if needed.
+        if (aggregation && typeof aggregation === 'string' && aggregation.length > 0) {
+            body.aggs = {
+                [aggregation]: {
+                    terms: {
+                        field: `${aggregation}.keyword`,
+                        missing: 'N/A',
+                        order: { _key: 'asc' },
+                        size: aggrLimit,
+                    },
+                },
+            };
+        }
+        // 1-0. default filter.
+        if (model?.stereo === null) {
+            // _add_must_not({ term: { [`stereo.keyword`]: '#' } });
+            this.addQueryTerm(body, 'must_not', { term: { [`stereo.keyword`]: '#' } });
+        }
+        // 1-1. support `hidden` flag.
+        if (options?.hidden !== undefined) {
+            const hidden = Boolean(options?.hidden);
+            if (hidden) {
+                this.addQueryTerm(body, 'must', { term: { hidden: 1 } });
+            }
+            else {
+                this.addQueryTerm(body, 'must_not', { term: { hidden: 1 } });
+            }
+        }
+        // 1-2. filter by attributes.
+        if (model && Object.keys(model).length > 0) {
+            (0, engine_1._inf)(this.logNS, `> filters =`, engine_1.$U.json(model));
+            Object.entries(model).forEach(([key, val]) => {
+                if (typeof val === 'string') {
+                    if (val === '') {
+                        this.addQueryTerm(body, 'must_not', { exists: { field: `${key}` } });
+                    }
+                    else if (val === '!') {
+                        this.addQueryTerm(body, 'must', { exists: { field: `${key}` } });
+                    }
+                    else {
+                        this.addQueryTerm(body, 'filter', { term: { [`${key}.keyword`]: val } });
+                    }
+                }
+                else if (val === null) {
+                    // ignore
+                }
+                else if (typeof val === 'number') {
+                    this.addQueryTerm(body, 'filter', { term: { [`${key}`]: val } });
+                }
+                else if (typeof val === 'object' && Array.isArray(val)) {
+                    this.addQueryTerm(body, 'must', {
+                        bool: {
+                            should: val.map(n => ({
+                                term: {
+                                    [`${key}.keyword`]: n,
+                                },
+                            })),
+                            minimum_should_match: 1,
+                        },
+                    });
+                }
+            });
+        }
+        // add sort term by `param.sort`
+        return this.addSortTerm(body, param);
+    }
+    /**
+     * Query 기준 추가하기.
+     */
+    addQueryTerm(body, term, query) {
+        if (!body)
+            throw new Error(`@body (SearchBody) is required!`);
+        if (!body.query || !body.query.bool) {
+            body.query = { bool: { filter: [], must: [], must_not: [] } };
+        }
+        //* helper function.
+        const _add_filter = (query) => {
+            const filter = [...(body.query.bool.filter || []), ...(Array.isArray(query) ? query : [query])];
+            body.query.bool.filter = filter;
+        };
+        const _add_must = (query) => {
+            const must = [...(body.query.bool.must || []), ...(Array.isArray(query) ? query : [query])];
+            body.query.bool.must = must;
+        };
+        const _add_must_not = (query) => {
+            const must_not = [
+                ...(body.query.bool.must_not || []),
+                ...(Array.isArray(query) ? query : [query]),
+            ];
+            body.query.bool.must_not = must_not;
+        };
+        if (term === 'filter') {
+            _add_filter(query);
+        }
+        else if (term === 'must') {
+            _add_must(query);
+        }
+        else if (term === 'must_not') {
+            _add_must_not(query);
+        }
+        else {
+            throw new Error(`@term(${term}) is not supported!`);
+        }
+        return body;
+    }
+    /**
+     * sort 기준 추가하기.
+     */
+    addSortTerm(body, param) {
+        if (!body.sort)
+            body.sort = { createdAt: { order: 'desc', missing: '_last' } };
+        if (param?.sort) {
+            const [sort, asc] = commons_1.$T.S(param?.sort).split(':', 2);
+            const order = `${asc || 'asc'}`;
+            const missing = order == 'desc' ? '_last' : '_first';
+            if (!sort)
+                body.sort = undefined;
+            else if (sort === 'id')
+                body.sort = { 'id.keyword': { order, missing: '_last' } };
+            else if (sort === 'name')
+                body.sort = { 'name.keyword': { order, missing: '_last' } };
+            else if (sort === 'brand')
+                body.sort = { 'brand.keyword': { order, missing: '_last' } };
+            else if (sort === 'color')
+                body.sort = { 'color.keyword': { order, missing: '_last' } };
+            else if (sort === 'order')
+                body.sort = { order: { order, missing } };
+            else if (sort === 'createdAt')
+                body.sort = { createdAt: { order, missing } };
+            else if (sort === 'updatedAt')
+                body.sort = { updatedAt: { order, missing } };
+            else if (sort)
+                body.sort = { [`${sort}.keyword`]: { order, missing } };
+        }
+        return body;
+    }
+    /**
+     * build filter for scan.
+     * @returns DynamoScanFilter
+     */
+    buildScanFilter(params) {
+        const filter = [
+            { key: 'ns', comparator: '=', value: this.parent.NS },
+            { key: 'type', comparator: '=', value: this.type },
+            { not: { key: 'stereo', operator: 'begins_with', value: '#' } },
+            { key: 'deletedAt', comparator: '=', value: 0 },
+        ];
+        // filter by params
+        if (params) {
+            Object.entries(params).forEach(([key, val]) => {
+                if (val === undefined || val === null) {
+                    // ignore.
+                }
+                else if (typeof val === 'string') {
+                    filter.push({ key, comparator: '=', value: val });
+                }
+                else {
+                    throw new Error(`400 NOT SUPPORTED - filter param[${engine_1.$U.json(params)}]`);
+                }
+            });
+        }
+        return filter;
+    }
+    /**
+     * execute scan with filter.
+     *
+     * @param $page
+     * @param filter
+     * @returns
+     */
+    async doScan($page, filter) {
+        const options = this.parent.dynamoOptions;
+        const idName = options.idName || '_id';
+        //* check if dummy table
+        if (!options?.tableName || options?.tableName?.endsWith('.yml'))
+            throw new Error(`400 NO DYNAMO - table:${options?.tableName ?? ''}!`);
+        const $scan = new cores_2.DynamoScanService(options);
+        //* scan all items with basic filter.
+        const list0 = [];
+        let $res;
+        while (true) {
+            $res = await $scan.scan(-1, $res?.last, filter);
+            $res.list?.forEach(N => {
+                delete N[idName];
+                list0.push(N);
+            });
+            if (!$res?.last[idName])
+                break;
+        }
+        //TODO - sort by some.
+        //* check if in unlimited. (or cut-off by page)
+        const limit = $page?.limit ?? 10;
+        const page = $page?.page ?? 0;
+        const unLimited = limit === -1 ? true : false;
+        const total = list0?.length || 0;
+        const _page = (list, page, limit) => {
+            if (!unLimited && limit === 0)
+                return [];
+            else if (unLimited)
+                return list;
+            return list.slice(page * limit, (page + 1) * limit);
+        };
+        const list = _page(list0, page, limit);
+        //* returns.
+        const aggr = [{ key: '#scan', count: total }];
+        return { list, total, limit, aggr };
+    }
+    /**
+     * execute scan-last with filter.
+     *
+     * @param $param ScanLastParams
+     * @returns
+     */
+    async doScanLast($param) {
+        const options = this.parent.dynamoOptions;
+        const limit = $param?.limit ?? 2;
+        const last = $param?.last;
+        const filter = $param?.filter;
+        if (!options?.tableName || options?.tableName?.endsWith('.yml')) {
+            throw new Error(`400 NO DYNAMO - table:${options?.tableName ?? ''}!`);
+        }
+        const $scan = new cores_2.DynamoScanService(options);
+        const $res = await $scan.scan(limit, last, filter);
+        const list = $res.list;
+        const total = engine_1.$U.N(list?.length || 0);
+        return (0, commons_1.onlyDefined)({
+            list,
+            total,
+            limit: limit,
+            count: $res?.count,
+            last: Object.keys($res?.last || {}).length === 0 ? undefined : $res?.last,
+        });
+    }
+    /**
+     * basic ElasticSearch Query.
+     * you can override this method for customization.
+     *
+     * @param limit pagination limit (default 10)
+     * @param page page number (starts from 0)
+     * @param filters model filters
+     * @param param (optional) addtion params
+     */
+    async list($page, $param, options) {
+        (0, engine_1._log)(this.logNS, `list(${$page?.limit ?? ''}, ${$page?.page ?? ''})..`);
+        const aggregation = options?.aggregation ?? 'stereo'; // default aggregation
+        //* use dynamo-scan if no search configuration.
+        if (!this.parent.hasSearchEngine()) {
+            const filter = this.buildScanFilter($param);
+            return this.doScan($page, filter);
+        }
+        // 1. build search request body
+        const body = this.buildQuery($page, $param, options);
+        // 2. search w/ query
+        const result = await this.parent.doSearch(body);
+        // 3. extract names only
+        const _aggr = () => {
+            if (!aggregation)
+                return [];
+            const buckets = result?.aggregations?.[aggregation]?.buckets;
+            buckets && (0, engine_1._log)(this.logNS, `> buckets =`, engine_1.$U.json(buckets));
+            if (!buckets || !Array.isArray(buckets))
+                return [];
+            return buckets?.reduce((L, bucket) => {
+                const key = commons_1.$T.S(bucket.key);
+                const count = commons_1.$T.N(bucket.doc_count, 0);
+                L.push({ key, count });
+                return L;
+            }, []);
+        };
+        // returns.
+        return { total: result.total, list: result.list, aggr: _aggr(), limit: $page?.limit, page: $page?.page };
+    }
+    /**
+     * list of projection fields
+     * - ONLY fields defined in `goods-model`
+     * - 모델별 추가 필드목록만 추림
+     */
+    listProjections(params) {
+        const includes = params?.includes ?? ['id', 'error', 'createdAt'];
+        const excludes = params?.excludes ?? ['extra', 'desc'];
+        const isSorted = params?.sorted ?? true;
+        const _notIn = (list, $ref) => list.filter(s => !excludes?.includes(s) && !includes?.includes(s) && !$ref?.includes(s));
+        const list = _notIn(this.FIELDS, CORE_FIELDS);
+        if (isSorted)
+            return [...includes, ...list.sort()];
+        return [...includes, ...list];
+    }
+    /**
+     * fetch all list of goods for filtering.
+     *
+     * @override if required.
+     */
+    buildSearchAll(params, sort) {
+        sort = sort ?? { createdAt: { order: 'asc', missing: '_last' } };
+        const [ns, type] = [this.parent.NS, this.type];
+        const size = params?.size ?? 500;
+        const _source = this.listProjections({ excludes: ['extra', 'meta'] });
+        const body = {
+            size,
+            query: {
+                bool: {
+                    filter: [{ term: { 'ns.keyword': ns } }, { term: { 'type.keyword': type } }],
+                },
+            },
+            _source,
+        };
+        if (sort)
+            body.sort = sort;
+        const _add_filter = (query) => {
+            const filter = [...(body.query.bool.filter || []), ...(Array.isArray(query) ? query : [query])];
+            body.query.bool.filter = filter;
+        };
+        const _add_must = (query) => {
+            const must = [...(body.query.bool.must || []), ...(Array.isArray(query) ? query : [query])];
+            body.query.bool.must = must;
+        };
+        const _add_must_not = (query) => {
+            const must_not = [
+                ...(body.query.bool.must_not || []),
+                ...(Array.isArray(query) ? query : [query]),
+            ];
+            body.query.bool.must_not = must_not;
+        };
+        _add_must({
+            bool: {
+                should: [
+                    { range: { deletedAt: { lte: 0 } } },
+                    {
+                        bool: {
+                            must_not: {
+                                exists: {
+                                    field: 'deletedAt',
+                                },
+                            },
+                        },
+                    },
+                ],
+                minimum_should_match: 1,
+            },
+        });
+        _add_must_not({ term: { stereo: '#' } });
+        _add_must_not({ term: { 'stereo.keyword': '#' } });
+        return body;
+    }
+    /**
+     * sync by scan with last record.
+     *
+     * **[좋은코드]**
+     * 1. 보기 좋아야함; 변수이름, 로직도 잘보이고, 함수의 목적
+     * 2. 테스트 가능한 코드 (또는 테스트가된 코드)
+     *  - Unit Test: 테스트 가능한 최소단위 (함수.. 블럭)
+     *  - Integrated Test: Group of Units (ex: my_sequence)
+     *
+     * @param $param
+     * @param options
+     * @returns
+     */
+    async doSyncScanLast($param, options) {
+        //* 1. doScanLast(w/filter by type); scan-size = 100
+        const $perf = commons_1.$T.perf();
+        const { list, last, count } = await this.doScanLast($param);
+        //* 2. chunk the list into smaller parts
+        const _makeChucks = (list, chunkSize) => {
+            const result = [];
+            for (let i = 0; i < list.length; i += chunkSize) {
+                result.push(list.slice(i, i + chunkSize));
+            }
+            return result;
+        };
+        const _saveBulk = async (operations) => {
+            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,
+                error: item.index.error,
+                status: item.index.status,
+            })) ?? [];
+            return { list, error: null };
+        };
+        const chunkSize = options?.size ?? 10;
+        const chunks = _makeChucks(list, chunkSize);
+        //* 3. use my_sequence to bulk each chunk sequentially
+        const chunkList = chunks.map((chunk, index) => ({
+            id: `${index}`,
+            error: null,
+            chunk,
+        }));
+        const _transformBulkOperations = (dataChunk) => {
+            return dataChunk.flatMap(doc => {
+                const { _id, ...items } = doc;
+                return [{ index: { _index: exports.$OS2.options?.indexName, _id: doc._id } }, items];
+            });
+        };
+        const results = await (0, helpers_1.my_sequence)(chunkList, async (N) => {
+            const operations = _transformBulkOperations(N.chunk);
+            const bulk = await _saveBulk(operations).catch(e => ({ list: [], error: (0, test_helper_1.GETERR)(e) }));
+            return { ...N, ...bulk };
+        });
+        // _log(this.logNS, `> results =`, $U.json(results));
+        // validate input and output _id
+        const _validateIds = (inputList, outputList) => {
+            const mismatchedIds = outputList.filter(item => !inputList.some(input => input._id === item._id));
+            if (mismatchedIds.length > 0) {
+                const mismatchedIdsList = mismatchedIds.map(item => item._id);
+                return { isValid: false, mismatchedIds: mismatchedIdsList };
+            }
+            return { isValid: true, mismatchedIds: [] };
+        };
+        //TODO - 초기 입력의 목록과 출력의 목록의 쌍이 서로 맞아야함.... @241230/steve
+        const itemList = results.reduce((L, N) => {
+            if (typeof N?.error == 'string')
+                L.push({ error: N.error });
+            if (N?.list) {
+                const validation = _validateIds(list, N?.list);
+                if (!validation.isValid)
+                    throw new Error(`Mismatched list id found: ${validation.mismatchedIds}`);
+                L.push(...N.list);
+            }
+            return L;
+        }, []);
+        //* returns
+        const took = $perf.took();
+        return (0, commons_1.onlyDefined)({ last: last, count: count, took, list: itemList });
+    }
+}
+exports.MyCoreManager = MyCoreManager;
+/**
+ * class: `MyCoreProxy`
+ * - common parent of proxy.
+ */
+class MyCoreProxy extends abstract_service_1.AbstractProxy {
+    managerProxies = {};
+    constructor(context, service, cacheScope) {
+        super(context, service, 2, cacheScope ?? `${NAME}:${service.NS}:`); //! use `env.NAME` as default cache scope.
+    }
+    /**
+     * check if in mocks mode.
+     * - override this to set mocks.
+     *
+     * @returns boolean
+     */
+    isMocks() {
+        return false;
+    }
+    /**
+     * register this.
+     */
+    register(mgr) {
+        const res = super.register(mgr);
+        // also add into proxy lookup.
+        this.addManagerProxy(mgr.$mgr.type, mgr);
+        return res;
+    }
+    /**
+     * add into proxy lookup.
+     */
+    addManagerProxy(modelType, proxy) {
+        if (this.managerProxies[modelType]) {
+            throw Error(`@modelType[${modelType}] is invalid - already exists!`);
+        }
+        else {
+            this.managerProxies[modelType] = proxy;
+        }
+    }
+    /**
+     * get from lookup table.
+     */
+    getManagerProxy(modelType) {
+        return this.managerProxies[modelType];
+    }
+    /**
+     * @override fetchIdentityAccess
+     * @deprecated not supported.
+     */
+    async fetchIdentityAccess(identityId, domain) {
+        const errScope = `fetchIdentityAccess(${identityId ?? ''}/${domain ?? ''})`;
+        throw new Error(`400 NOT SUPPORTED - ${errScope}`);
+    }
+    /**
+     * get the `identity-token` (as session) from current req-context.
+     * - 1차 호출(front에서) 에서는 이 세션이 꼭 필요함.
+     * - 2차 호출(protocol이용) 에서는 선택사항으로, 조절가능해야함! (#TODO - 이걸 어떻게 구불할것인가?)
+     * - 로컬) 로컬 개발에서는 시뮬레이션 방법은 #TODO
+     *
+     * @param options.throwable flag to throw (default true)
+     */
+    getCurrentSession(options) {
+        // const useSession = !$U.env('LOCAL_ACCOUNT') ? $U.env('USE_SESSION') : null;
+        const throwable = options?.throwable ?? true;
+        const normalize = options?.normalize ?? true;
+        const useSession = options?.useSession ?? true;
+        const LOCAL_ACCOUNT = commons_1.$T.S(options?.LOCAL_ACCOUNT ?? engine_1.$U.env('LOCAL_ACCOUNT'));
+        const USE_SESSION = commons_1.$T.S(options?.USE_SESSION ?? engine_1.$U.env('USE_SESSION'));
+        LOCAL_ACCOUNT && (0, engine_1._inf)(this.service.NS, `> LOCAL_ACCOUNT =`, LOCAL_ACCOUNT);
+        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.
+        //* 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);
+            if (typeof data?.error === 'string')
+                throw new Error(`@file[${file}] is invalid, ${data.error}`);
+            if (data?.context?.identity)
+                return data?.context?.identity;
+            return data;
+        };
+        const _default = () => {
+            //INFO - `userAgent`가 있다면, identity 생성 프로세스가 제대로 실행된것으로 판단해도됨! @240620.
+            if (typeof context?.identity?.userAgent == 'string')
+                return context?.identity;
+            //TODO - 아래 코드는 개선의 여지가 있음(문제점???) @241210
+            // if (typeof (context?.identity as any)?.identityId == 'string') return context?.identity;
+            return null;
+        };
+        //* load the `identity-token` from context or local json file.
+        const _session = () => {
+            //INFO - `userAgent`가 있다면, identity 생성 프로세스가 제대로 실행된것으로 판단해도됨! @240620.
+            const $idt = context?.identity;
+            //* Local 이면서 meta 정보가 있다면, 그걸로 identity 재구성함 @251212.
+            if (isLocal && typeof $idt?.meta === 'string' && $idt?.meta.length > 0) {
+                const $jwt = engine_1.$U.jwt('');
+                return $jwt.decode(context?.identity?.meta, { complete: false });
+            }
+            if (typeof $idt?.userAgent == 'string') {
+                //NOTE - `express` 에서 넘어온 경우 `identityPoolId=null`으로 가능함. (but apiKey should be empty) @251031
+                const fromExpress = typeof $idt?.identityPoolId === 'undefined' || $idt?.identityPoolId === null;
+                if (!fromExpress || typeof $idt?.apiKey === 'string') {
+                    return context?.identity;
+                }
+            }
+            //TODO - 아래 코드는 개선의 여지가 있음(문제점???) @241210
+            //* 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') {
+                    //* 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;
+                    }
+                    return _default();
+                }
+                else if (typeof useSession === 'string' || useSession) {
+                    return _load(useSession);
+                }
+                return _default();
+            }
+            return _default();
+        };
+        const $sess = _session();
+        // _inf(this.service.NS, `> use-session =`, $U.json($ses));
+        if (throwable && !isLocal) {
+            const eCode = `403 IDENTITY-TOKEN`;
+            const err = $sess?.error
+                ? `error:${$sess?.error}`
+                : $sess?.meta
+                    ? `meta:${typeof $sess?.meta == 'string' ? $sess?.meta : engine_1.$U.json($sess?.meta)}`
+                    : 'check x-lemon-identity';
+            //* validate conditions..
+            if (!$sess)
+                throw new Error(`${eCode} - .identity (IdentityToken) is required - context:${engine_1.$U.json(context)}`);
+            if ($sess?.sid === undefined)
+                throw new Error(`${eCode} - ${err}`);
+            if (!$sess?.sid)
+                throw new Error(`${eCode} - .sid (site-id) is required!`);
+            if (!$sess?.uid)
+                throw new Error(`${eCode} - .uid (user-id) is required!`);
+        }
+        //* normalize for the internal.
+        const sid = normalize && $sess?.sid?.startsWith('#') ? null : commons_1.$T.S2($sess?.sid);
+        const uid = normalize && $sess?.uid?.startsWith('#') ? null : commons_1.$T.S2($sess?.uid);
+        //* returns.
+        return $sess ? { ...$sess, sid, uid } : null;
+    }
+    /**
+     * find the current identity-id from context.
+     * - or, use env[LOCAL_ACCOUNT]
+     */
+    asCurrentIdentityId = (context) => {
+        context = context ?? this.context;
+        //* 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;
+        }
+        return context && (0, helpers_1.getIdentityId)(context);
+    };
+    /**
+     * assert context condition.
+     */
+    assertContext(params, 
+    /** (optional) */
+    options) {
+        const context = options?.context ?? this.context;
+        const throwable = options?.throwable ?? true;
+        const errScope = options?.errScope ?? `assertContext()`;
+        const $idt = context?.identity;
+        const isS = (s) => typeof s === 'string' && s?.length > 0;
+        //* 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.
+        const isAuthed = isS($idt?.identityProvider) && isS($idt?.identityId) && isS($idt?.identityPoolId);
+        //* check if has role
+        const _hasRole = (role) => {
+            const $sess = this.getCurrentSession({ throwable: false, context });
+            return $sess?.roles?.includes(role);
+        };
+        const errCode = `403 NOT ALLOWED`;
+        if (typeof params?.isLocal == 'boolean' && params?.isLocal != isLocal) {
+            if (throwable)
+                throw new Error(`${errCode} - invalid isLocal[${params?.isLocal}] @${errScope}`);
+            return false;
+        }
+        if (typeof params?.isSigned == 'boolean' && params?.isSigned != isSigned) {
+            if (throwable)
+                throw new Error(`${errCode} - invalid isSigned[${params?.isSigned}] @${errScope}`);
+            return false;
+        }
+        if (typeof params?.isAuthed == 'boolean' && params?.isAuthed != isAuthed) {
+            if (throwable)
+                throw new Error(`${errCode} - invalid isAuthed[${params?.isAuthed}] @${errScope}`);
+            return false;
+        }
+        if (typeof params?.hasRole == 'string' && !_hasRole(params?.hasRole)) {
+            if (throwable)
+                throw new Error(`${errCode} - invalid hasRole[${params?.hasRole}] @${errScope}`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * check if current context has `admin` access
+     * 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.
+     *
+     * @param role (default) admin
+     * @param options optionals
+     * @returns boolean
+     */
+    hasAdminRole(role, options) {
+        role = commons_1.$T.S2(role, 'admin');
+        const context = (options?.context ?? this.context);
+        const $option = { ...options, throwable: false };
+        if (this.assertContext({ isLocal: true }, $option))
+            return true;
+        if (this.assertContext({ isSigned: true, isAuthed: false }, $option))
+            return true;
+        if (this.assertContext({ isAuthed: true, hasRole: role }, $option))
+            return true;
+        //TODO 아래는 임시로 role에서 바로 체크하도록함! @251212/steve (샘픔의 session-dev.json를 이용할경우 admin 체크가 잘 안됨)
+        if (context?.identity?.roles?.includes(role))
+            return true;
+        return false;
+    }
+    /**
+     * prepare `next-context` w/ the customized { domain, userAgent }
+     *
+     * @param identityId the target identity-id
+     * @param options additional options.
+     */
+    asNextContext(identityId, options) {
+        const $ctx = this.context;
+        identityId = identityId ?? this.asCurrentIdentityId($ctx);
+        const identity = options?.identity ?? $ctx.identity;
+        const session = options?.session ?? this.getCurrentSession({ throwable: false });
+        const $ctx2 = {
+            ...$ctx,
+            domain: options?.domain ?? $ctx.domain,
+            userAgent: options?.userAgent ?? $ctx.userAgent,
+            identity: {
+                ...session,
+                ...identity,
+                identityId,
+            },
+        };
+        return $ctx2;
+    }
+    /**
+     * from `identity-token`, make base of model { sid, uid }
+     *
+     * @param proxy the current proxy.
+     * @returns base model
+     */
+    async makeModelBase(model, options) {
+        const useSession = options?.useSession ?? false;
+        const throwable = options?.throwable ?? false;
+        const base = model ?? {};
+        // STEP.0 populate with current parent.
+        if (options?.parent) {
+            const parent = options.parent;
+            base['sid'] = base['sid'] ?? parent?.sid;
+            base['uid'] = base['uid'] ?? parent?.uid;
+        }
+        // STEP.1 use session if applicable
+        if (useSession) {
+            const parent = this.getCurrentSession({ throwable });
+            base['sid'] = base['sid'] ?? parent?.sid;
+            base['uid'] = base['uid'] ?? parent?.uid;
+        }
+        return base;
+    }
+    /**
+     * Check if the user can perform a specific action on a model.
+     * - override this method to implement custom logic.
+     *
+     * @param action The action to check.
+     * @param model The model to check against. (.type is used to find the manager-proxy)
+     * @param options Optional parameters for the check.
+     * @returns True if the action is allowed, false otherwise.
+     */
+    canDo(action, model, options) {
+        const type = model?.type;
+        if (typeof type !== 'string')
+            throw new Error(`400 INVALID - @model.type (string) is required!`);
+        const $prx = this.getManagerProxy(type);
+        if (!$prx)
+            return false;
+        return $prx.canDo(action, model, options);
+    }
+}
+exports.MyCoreProxy = MyCoreProxy;
+/**
+ * class: `MyProxy`
+ * - common parent of manager-proxy.
+ */
+class MyManagerProxy extends abstract_service_1.ManagerProxy {
+    proxy;
+    constructor(proxy, mgr) {
+        super(proxy, mgr);
+        this.proxy = proxy;
+    }
+    /**
+     * @override the default `normal()` to support _name.
+     */
+    normal = (N) => Object.keys(N || {}).reduce((M, k) => {
+        //NOTE - imporved of basic `normal()` in core not to ignore `_` properties.
+        if (k == '_id' || !this.$mgr.FIELDS.includes(k))
+            return M;
+        const v = N[k];
+        //! `null` 은 DynamoDB에서 비어있는 문자임.
+        M[k] = v === null ? '' : v;
+        return M;
+    }, {});
+    /**
+     * pack the query parameter for list
+     * - `param` has the string values only including '', '!'
+     * - `model` has the valid data type. (number | string | ... )
+     *
+     * ```ts
+     * let model = bodyToModel(param)
+     * ```
+     *
+     * @param param the original query parameter.
+     * @param model the transformed model from `param`.
+     * @param options (optional)
+     * @returns
+     */
+    packSearchParam(param, model, options) {
+        const type = this.$mgr.type;
+        const useSession = options?.useSession ?? false;
+        const throwable = options?.throwable ?? true;
+        const errScope = options?.errScope ?? `packSearchParam(${type})`;
+        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);
+        const _hasAdm = () => this.proxy.hasAdminRole('admin');
+        // parse params
+        const sort = _has('sort') ? commons_1.$T.S2(param?.sort, '') : undefined;
+        const $page = (0, commons_1.parsePaginateParam)({ ...param, sort }, { limit: options?.limit ?? 10, page: 0 });
+        if ($page.page < 0)
+            throw new Error(`@page[${$page.page}] is invalid - ${errScope}`);
+        // extract filtering by properties.
+        // WARN - has no internal properties like { sid, gid, uid }
+        const $param = this.$mgr.FIELDS.reduce((M, k) => {
+            const key = k;
+            const val = model && model[key];
+            const qry = param && param[k];
+            //* high priorty to param for not transformed field.
+            if (qry === '' || qry === '!')
+                M[key] = qry;
+            else if (val !== undefined)
+                M[key] = val;
+            return M;
+        }, {});
+        // use w/ `identity-token` (known as session)
+        if (useSession && !isLocal) {
+            if (_hasAdm()) {
+                $param['sid'] = _has('sid') ? (_val('sid') === '0' ? session?.sid : _val('sid')) : session?.sid;
+            }
+            else {
+                $param['sid'] = session?.sid;
+            }
+            //* use the current session's uid.
+            if (_has('uid'))
+                $param['uid'] = _val('uid') === '0' ? session?.uid : _val('uid');
+        }
+        else {
+            if (_has('sid'))
+                $param['sid'] = _val('sid');
+            if (_has('uid'))
+                $param['uid'] = _val('uid') === '0' ? session?.uid : _val('uid');
+        }
+        //* returns params.
+        return { $page, $param };
+    }
+    /**
+     * override this to validate request'body.
+     * @param model model from request.
+     * @param modelId (optional) modelId if to update the target model.
+     * @return validated model to save.
+     */
+    async validateModel(model, modelId) {
+        const $org = modelId ? await this.get(modelId, true) : null;
+        const validated = await this.$mgr.validateModel(model, $org);
+        return validated;
+    }
+    /**
+     * callback before saving model.
+     * - could change field before saving.
+     *
+     * @param model the last model to save.
+     * @param $org (optional) original model (null if creating)
+     */
+    async onBeforeSave(model, $org) {
+        return model;
+    }
+    /**
+     * callback after saving model.
+     * - could trigger the next step if created.
+     *
+     * @param model the saved model (null if deleted)
+     * @param $org (optional) original model (null if new created)
+     */
+    async onAfterSave(model, $org) {
+        return model;
+    }
+    /**
+     * generate the next id
+     */
+    async nextId(step) {
+        return this.$mgr.nextId(step).then(n => commons_1.$T.S2(n));
+    }
+    /**
+     * create new model
+     * - use `.id` or `nextId()` for model-id
+     * - validate model in seperate way before using this.
+     *
+     * @param model creation model
+     * @param validate (optional) flag to validate (default is true)
+     */
+    async makeModel(model, validate) {
+        const errScope = `makeModel(${this.$mgr.type}/${model?.id ?? ''})`;
+        if (!model)
+            throw new Error(`@model (${this.$mgr.type}-model) is required - ${errScope}`);
+        validate = validate ?? true;
+        // use the custome id or new generated id.
+        const hasId = !!model.id;
+        const modelId = hasId ? commons_1.$T.S2(model.id) : await this.nextId();
+        // make default model as base.
+        const $def0 = this.$mgr.buildDefault(modelId);
+        const $def2 = this.override($def0, model); //! 초기생성(INSERT)에 대부분의 필드값 채워주기.
+        const $def3 = validate ? await this.validateModel({ ...$def2, id: modelId }, null) : $def2;
+        // overwrite (or update) the model.
+        const $org = await this.get(modelId, { ...$def3 });
+        if ($org?.id !== modelId)
+            throw new Error(`.id[${model?.id}] is invalid (mismatched ${modelId}) - ${errScope}`);
+        const $res = hasId ? this.override($org, $def3) : $org;
+        return $res; //! return the model with id.
+    }
+    /**
+     * Check if the current user can perform the specified action on the given model.
+     * - override this method to implement custom logic.
+     *
+     * @param action The action to check.
+     * @param model The model to check against.
+     * @param options Additional options for the check.
+     * @returns True if the action is allowed, false otherwise.
+     */
+    canDo(action, model, options) {
+        const errScope = options?.errScope ?? `canDo(${action ?? ''}:${this.$mgr.type}/${model?.id ?? '-'})`;
+        const useSession = options?.useSession ?? this.proxy.service.isUseSession();
+        const throwable = options?.throwable ?? true;
+        const context = options?.context;
+        // STEP.0 validate parameters.
+        const _act = commons_1.$T.asLut(action, $LUT.CanDoAction, { throwable: false, default: null });
+        if (!_act || typeof _act !== 'string')
+            throw new Error(`400 INVALID - action[${action ?? ''}] is invalid @${errScope}`);
+        // no session but required.
+        const $sess = this.proxy.getCurrentSession({ throwable, useSession, context });
+        if (useSession && !$sess)
+            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) {
+                case 'list':
+                case 'read':
+                case 'create':
+                    // (default) action is allowed if sid matches or no sid.
+                    if (!M.sid)
+                        return true;
+                    if (S.sid === M.sid)
+                        return true;
+                    break;
+                case 'update':
+                case 'delete':
+                    // (default) action is allowed if sid&uid matches.
+                    //* v5: a `sid`-less record is admin-only for update/delete (B5 § 6.4).
+                    if (!M.sid)
+                        break;
+                    if (S.sid === M.sid && S.uid === M.uid)
+                        return true;
+                    break;
+                default:
+                    throw new Error(`400 INVALID - action[${_act}] is invalid @${errScope}`);
+            }
+        }
+        // not allowed.
+        if (throwable)
+            throw new Error(`403 NOT ALLOWED - action[${_act}] is invalid @${errScope}`);
+        return false;
+    }
+    /**
+     * read multiple nodes.
+     * @param ids list of object-ids
+     * @param throwable (optional) flag to throw error if not found
+     */
+    async mget(ids, options) {
+        const throwable = typeof options === 'boolean' ? options : options?.throwable ?? true;
+        if (!ids || ids.length === 0)
+            return [];
+        const result = [];
+        const toFetch = [];
+        const indexMap = {};
+        //* STEP.1 check cached items
+        ids.forEach((id, index) => {
+            const err404 = `404 NOT FOUND - proxy/${this.$mgr.type}/id:${id}`;
+            //* already marked as null (404)
+            if (this._org[id] === null) {
+                if (throwable)
+                    throw new Error(err404);
+                result[index] = null;
+                return;
+            }
+            //* found in _new
+            const N = this._new[id];
+            if (N !== undefined) {
+                result[index] = N;
+                return;
+            }
+            //* need to fetch
+            if (!indexMap[id]) {
+                indexMap[id] = [];
+                toFetch.push(id);
+            }
+            indexMap[id].push(index);
+        });
+        //* STEP.2 batch read from storage
+        if (toFetch.length > 0) {
+            const context = this.proxy.asNextContext();
+            //TODO [Steve] 여기서 갑자기 storage 에서 읽어오는부분을 proxy 에서 하도록 개선 필요해 보임 @260608.
+            const $res = await this.$mgr.storage.storage.doReadMulti(this.$mgr.type, toFetch, { throwable, context });
+            const successMap = {};
+            ($res?.success || []).forEach(model => {
+                const id = model.id;
+                if (id)
+                    successMap[id] = model;
+            });
+            //* STEP.3 save to cache and build result
+            toFetch.forEach(id => {
+                const M = successMap[id];
+                if (M) {
+                    const M2 = this.normal(M);
+                    this._org[id] = M2;
+                    const M3 = JSON.parse(engine_1.$U.json(M2));
+                    this._new[id] = M3;
+                    indexMap[id].forEach(index => {
+                        result[index] = M3;
+                    });
+                }
+                else {
+                    this._org[id] = null;
+                    const err404 = `404 NOT FOUND - proxy/${this.$mgr.type}/id:${id}`;
+                    indexMap[id].forEach(index => {
+                        if (throwable)
+                            throw new Error(err404);
+                        result[index] = null;
+                    });
+                }
+            });
+        }
+        return result;
+    }
+    /**
+     * update multiple nodes.
+     * @param updates list of models (should include id)
+     */
+    async mset(updates) {
+        if (!updates || updates.length === 0)
+            return [];
+        const result = [];
+        for (const model of updates) {
+            const id = model.id;
+            if (!id)
+                throw new Error(`@id is required - proxy/${this.$mgr.type}/mset()!`);
+            const O = await this.get(id);
+            result.push(this.override(O, model));
+        }
+        return result;
+    }
+}
+exports.MyManagerProxy = MyManagerProxy;
+/**
+ * class: `OS2Service`
+ * - Master 권한 전용 Elasticsearch 관리 서비스
+ * - service for OS2: data path via FGAC (`$fgac`), index management via the master client.
+ */
+class OS2Service extends cores_1.OS2CoreService {
+    $fgac;
+    /**
+     * constructor (no client here; the master client is created on first `client` access)
+     */
+    constructor(options, fgac) {
+        super(options);
+        this.$fgac = fgac;
+    }
+    /**
+     * build the master client: `auth` is read from config now (after engine init), and set only when both exist.
+     */
+    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
+     */
+    async deleteIndex(indexName) {
+        (0, engine_1._log)(NS, `- deleteIndex(${indexName})`);
+        const client = this.client;
+        const res = await client.indices.delete({ index: indexName }).catch(cores_1.$ERROR.handler('delete', 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;
+        }));
+        return res;
+    }
+    /**
+     * save single item
+     *
+     * @param id - id
+     * @param item - item to save
+     * @param type - document type (default: doc-type given at construction time)
+     */
+    async saveItem(id, item) {
+        const { indexName, idName } = this.options;
+        (0, engine_1._log)(NS, `- saveItem(${id})`);
+        // const { client } = instance(endpoint);
+        // prepare item body and autocomplete fields
+        const body = { ...item, [idName]: id };
+        const body2 = this.popullateAutocompleteFields(body);
+        const params = { index: indexName, id, body: body2 };
+        if (idName === '_id')
+            delete params.body[idName]; //WARN! `_id` is reserved in ES6.
+        (0, engine_1._log)(NS, `> params[${id}] =`, engine_1.$U.json(params));
+        //NOTE - use npm `elasticsearch#13.2.0` for avoiding error.
+        const res = await this.$fgac.doFgacCreate(params).catch(e => {
+            const msg = (0, test_helper_1.GETERR)(e);
+            if (msg.startsWith('409 VERSION CONFLICT ENGINE') || msg.startsWith('409 Conflict')) {
+                const param2 = { index: indexName, id, body: { ...body2 } };
+                return this.$fgac.doFgacSave(param2);
+            }
+            throw e;
+        });
+        (0, engine_1._log)(NS, `> create[${id}].res =`, engine_1.$U.json({ ...res, meta: undefined }));
+        const _version = engine_1.$U.N(res?._version, 0);
+        const _id = res?._id;
+        const res2 = { ...body, _id, _version };
+        return res2;
+    }
+    /**
+     * bulk save multiple items using elasticsearch client
+     *
+     * @param items - array of items to save
+     */
+    async bulkItems(items, options) {
+        const errScope = `bulkItems(${this.options.indexName})`;
+        const { indexName } = this.options;
+        //* 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}`);
+        const { failedItems, bulkBody } = items.reduce((acc, item) => {
+            const id = item[idName];
+            if (!id) {
+                acc.failedItems.push({
+                    reason: `@${idName} is invalid - ${errScope}`,
+                    item,
+                });
+                return acc;
+            }
+            const body = { ...item, [idName]: id };
+            const body2 = this.popullateAutocompleteFields(body);
+            if (idName === '_id')
+                delete body2['_id']; // Remove reserved _id field
+            acc.bulkBody.push({ index: { _index: indexName, _id: id } });
+            acc.bulkBody.push(body2);
+            return acc;
+        }, {
+            failedItems: [],
+            bulkBody: [],
+        });
+        if (bulkBody.length === 0)
+            return { success: 0, failed: failedItems.length, failedItems };
+        const res = await this.$fgac.doFgacBulk({ index: indexName, body: bulkBody }).catch(cores_1.$ERROR.handler('bulk', e => {
+            (0, engine_1._err)(NS, `> bulkItems[${indexName}].err =`, e);
+            throw e;
+        }));
+        // const res = await client.bulk({ body: bulkBody }).catch(
+        //     $ERROR.handler('bulk', e => {
+        //         _err(NS, `> bulkItems[${indexName}].err =`, e);
+        //         throw e;
+        //     }),
+        // );
+        const itemsRes = res?.items ?? [];
+        const failedFromBulk = itemsRes
+            .filter((r) => r.index?.error)
+            .map((r) => ({
+            reason: r.index.error?.reason || 'unknown error',
+            item: r.index,
+        }));
+        failedItems.push(...failedFromBulk);
+        const failed = failedItems.length;
+        const success = itemsRes.length - failed;
+        (0, engine_1._log)(NS, `> bulkItems done: success=${success}, failed=${failed},`);
+        return { success, failed, failedItems };
+    }
+    /**
+     * push item for time-series data (via FGAC; the result is the response body itself).
+     *
+     * @param item - item to push
+     */
+    async pushItem(item) {
+        const { indexName } = this.options;
+        const id = item.id ?? '';
+        const body = { ...item };
+        const body2 = this.popullateAutocompleteFields(body);
+        (0, engine_1._log)(NS, `- pushItem(${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);
+        const res = await this.$fgac.doFgacSave(params).catch(
+        // $ERROR.throwAsJson,
+        cores_1.$ERROR.handler('index', e => {
+            (0, engine_1._err)(NS, `> index[${indexName}].err =`, e instanceof Error ? e : engine_1.$U.json(e));
+            throw e;
+        }));
+        // {"_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 }));
+        //* 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;
+    }
+    /**
+     * read item with projections
+     *
+     * @param id - item-id
+     * @param views - projections
+     */
+    async readItem(id, views) {
+        const { indexName } = this.options;
+        (0, engine_1._log)(NS, `- readItem(${id})`);
+        const params = { index: indexName, id };
+        if (views) {
+            const fields = [];
+            const keys = Array.isArray(views) ? views : Object.keys(views);
+            keys.forEach((k) => {
+                fields.push(k);
+            });
+            params._source = fields;
+        }
+        (0, engine_1._log)(NS, `> params[${id}] =`, engine_1.$U.json(params));
+        // const { client } = instance(endpoint);
+        const res = await this.$fgac.doFgacRead(params).catch(
+        // $ERROR.throwAsJson,
+        cores_1.$ERROR.handler('read', e => {
+            const msg = (0, test_helper_1.GETERR)(e);
+            if (msg.startsWith('404 NOT FOUND'))
+                throw new Error(`404 NOT FOUND - id:${id}`);
+            if (msg.startsWith('404 INDEX NOT FOUND'))
+                throw new Error(`404 NOT FOUND - index:${indexName}`);
+            throw e;
+        }));
+        (0, engine_1._log)(NS, `> read[${id}].res =`, engine_1.$U.json({ ...res, meta: undefined }));
+        const _id = res._id;
+        const _version = res._version;
+        const data = res?._source || res._source || {};
+        // delete internal (analyzed) field
+        delete data[cores_1.OS2CoreService.DECOMPOSED_FIELD];
+        delete data[cores_1.OS2CoreService.QWERTY_FIELD];
+        const res2 = { ...data, _id, _version };
+        return res2;
+    }
+    /**
+     * delete item with projections
+     *
+     * @param id - item-id
+     */
+    async deleteItem(id) {
+        const { indexName } = this.options;
+        (0, engine_1._log)(NS, `- deleteItem(${id})`);
+        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 => {
+            const msg = (0, test_helper_1.GETERR)(e);
+            if (msg.startsWith('404 NOT FOUND'))
+                throw new Error(`404 NOT FOUND - id:${id}`);
+            if (msg.startsWith('404 INDEX NOT FOUND'))
+                throw new Error(`404 NOT FOUND - index:${indexName}`);
+            throw e;
+        }));
+        (0, engine_1._log)(NS, `> delete[${id}].res =`, engine_1.$U.json({ ...res, meta: undefined }));
+        const _id = res._id;
+        const _version = res._version;
+        const data = res._source || res._source || {};
+        const res2 = { ...data, _id, _version };
+        return res2;
+    }
+    /**
+     * update item (throw if not exist)
+     * `update table set a=1, b=b+2 where id='a1'`
+     * 0. no of `a1` -> 1,2 (created)
+     * 1. a,b := 10,20 -> 11,22
+     * 2. a,b := 10,null -> 11,2 (upsert)
+     * 3. a,b := null,20 -> 1,22
+     *
+     * @param id - item-id
+     * @param item - item to update
+     * @param increments - item to increase
+     * @param options - (optional) request option of client.
+     */
+    async updateItem(id, item, increments, options) {
+        const errScope = `updateItem(${id ?? ''})`;
+        if (increments)
+            throw new Error(`400 NOT SUPPORTED - invalid increments[${engine_1.$U.json(increments)}] @${errScope}`);
+        // return this.saveItem(id, item);
+        //NOTE - 이후 saveItem() 호출을 위한 tricky solution.
+        throw new Error(`404 NOT FOUND - ${errScope}`);
+    }
+    /**
+     * run search and get the raw 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 searchRaw(body, searchType) {
+        if (!body)
+            throw new Error('@body (SearchBody) is required');
+        const { indexName } = this.options;
+        (0, engine_1._log)(NS, `- search(${indexName}, ${searchType || ''})....`);
+        (0, engine_1._log)(NS, `> body =`, engine_1.$U.json(body));
+        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;
+        }));
+        //* return raw results.
+        return $res;
+    }
+}
+exports.OS2Service = OS2Service;
+/**
+ * type: `OS2FGACManager`
+ * - FGAC(Fine Grained Access Controll) Proxy for OS2
+ */
+class OS2FGACManager {
+    _fgacProxy;
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    hello = () => `FGACService`;
+    get proxy() {
+        const errScope = `OS2FGACManager(${this.options?.indexName ?? ''})`;
+        if (!this._fgacProxy) {
+            const endpoint = this.options.endpoint;
+            const host = endpoint.split('://')[1];
+            const $config = engine_1.$engine.module('config');
+            const OS2_JWT_TOKEN = engine_1.$U.env('OS2_JWT_TOKEN', '');
+            const message = engine_1.$U.env('OS2_MESSAGE', '');
+            const signature = $config?.config?.get('OS2_SIGNATURE');
+            const jwtToken = OS2_JWT_TOKEN !== '' ? OS2_JWT_TOKEN : `${message}.${signature}`; // if OS2_JWT_TOKEN is provided, use it
+            const sigConfig = {
+                accessKey: '**',
+                secretKey: '**',
+                region: 'ap-northeast-2',
+                serviceName: 'es',
+                host,
+            };
+            (0, engine_1._log)(NS, `> sigConfig =`, engine_1.$U.json({ ...sigConfig, secretKey: `${sigConfig?.secretKey ? '***' : ''}` }));
+            const headers = {
+                Authorization: `Bearer ${jwtToken}`,
+                'Content-Type': 'application/json',
+            };
+            this._fgacProxy = (0, helpers_1.createSigV4Proxy)('fgac', endpoint, sigConfig, { headers });
+        }
+        return this._fgacProxy;
+    }
+    /** FGAC 기반 검색 */
+    async doFgacSearch(params) {
+        const index = params?.index ?? '';
+        const body = (0, commons_1.onlyDefined)(params?.body ?? undefined);
+        const queryParams = params?.search_type ? { search_type: params?.search_type } : undefined;
+        return this.proxy.doProxy('POST', index, `_search`, queryParams, body);
+    }
+    /** FGAC 기반 읽기: client.get() 대응 */
+    async doFgacRead(params) {
+        const index = params?.index ?? '';
+        const id = encodeURIComponent(params?.id ?? '');
+        const body = (0, commons_1.onlyDefined)(params?.body ?? undefined);
+        return this.proxy.doProxy('GET', index, `_doc/${id}`, undefined, body);
+    }
+    /** FGAC 기반 저장: client.index() 대응 */
+    async doFgacSave(params) {
+        const index = params?.index ?? '';
+        const id = encodeURIComponent(params?.id ?? '');
+        const body = (0, commons_1.onlyDefined)(params?.body ?? undefined);
+        return this.proxy.doProxy('PUT', index, `_doc/${id}`, undefined, body);
+    }
+    /** FGAC 기반 저장: client.index() 대응 */
+    async doFgacBulk(bulk) {
+        const index = bulk?.index ?? '';
+        const body = bulk?.body ?? [];
+        const errScope = `doFgacBulk(${index})`;
+        if (!Array.isArray(body))
+            throw new Error(`@body(array) is required - ${errScope}`);
+        if (body.length === 0)
+            return [];
+        // 사전 포맷된 bulkBody를 JSONL 문자열로 변환
+        const content = body.map(line => engine_1.$U.json(line)).join('\n') + '\n';
+        return this.proxy.doProxy('POST', index, `_bulk`, undefined, content);
+    }
+    /** FGAC 기반 업데이트: client.update() 대응 */
+    async doFgacUpdate(params) {
+        const index = params?.index ?? '';
+        const id = encodeURIComponent(params?.id ?? '');
+        const body = (0, commons_1.onlyDefined)(params?.body ?? undefined);
+        return this.proxy.doProxy('POST', index, `_update/${id}`, undefined, body);
+    }
+    /** FGAC 기반 삭제: client.delete() 대응 */
+    async doFgacDelete(params) {
+        const index = params?.index ?? '';
+        const id = encodeURIComponent(params?.id ?? '');
+        return this.proxy.doProxy('DELETE', index, `_doc/${id}`);
+    }
+    /** FGAC 기반 Create (Strict - 존재하면 실패): client.create() 대응 */
+    async doFgacCreate(params) {
+        const index = params?.index ?? '';
+        const id = encodeURIComponent(params?.id ?? '');
+        const body = (0, commons_1.onlyDefined)(params?.body ?? undefined);
+        return this.proxy.doProxy('PUT', index, `_doc/${id}`, { op_type: 'create' }, body);
+    }
+    /** FGAC 기반 인덱스 삭제: client.indices.delete() 대응 */
+    async doFgacDeleteIndex(index) {
+        return this.proxy.doProxy('DELETE', index, '');
+    }
+    /**
+     * FGAC 기반 인덱스 설명: client.indices.describe() 대응
+     */
+    async doFgacDescribe(index) {
+        const errScope = `doFgacDescribe(${index})`;
+        if (!index)
+            throw new Error(`.index(string) is required - ${errScope}`);
+        // 1) 설정 조회
+        const resSettings = await this.doFgacGetSettings(index);
+        //    resSettings.body 안에 { [index]: { settings: { … } } } 형태로 들어옴
+        // 2) 매핑 조회
+        const resMappings = await this.doFgacGetMapping(index);
+        //    resMappings.body 안에 { [index]: { mappings: { … } } } 형태로 들어옴
+        return {
+            settings: resSettings[index]?.settings || {},
+            mappings: resMappings[index]?.mappings || {},
+        };
+    }
+    /**
+     * FGAC 기반 인덱스 Settings 변경: client.indices.putSettings() 대응
+     */
+    async doFgacPutSettings(index, settings) {
+        const errScope = `doFgacPutSettings(${index})`;
+        if (!index)
+            throw new Error(`.index(string) is required - ${errScope}`);
+        return this.proxy.doProxy('PUT', index, `_settings`, undefined, { settings });
+    }
+    /**
+     * FGAC 기반 인덱스 Settings 조회: client.indices.getSettings() 대응
+     */
+    async doFgacGetSettings(index) {
+        const errScope = `doFgacGetSettings(${index})`;
+        if (!index)
+            throw new Error(`.index(string) is required - ${errScope}`);
+        return this.proxy.doProxy('GET', index, `_settings`);
+    }
+    /**
+     * FGAC 기반 인덱스 Mapping 조회: client.indices.getMapping() 대응
+     */
+    async doFgacGetMapping(index) {
+        const errScope = `doFgacGetMapping(${index})`;
+        if (!index)
+            throw new Error(`.index(string) is required - ${errScope}`);
+        return this.proxy.doProxy('GET', index, `_mapping`);
+    }
+    /**
+     * FGAC 기반 인덱스 Mapping 변경: client.indices.putMapping() 대응
+     */
+    async doFgacPutMapping(index, mapping) {
+        const errScope = `doFgacPutMapping(${index})`;
+        if (!index)
+            throw new Error(`.index(string) is required - ${errScope}`);
+        return this.proxy.doProxy('PUT', index, `_mapping`, undefined, mapping);
+    }
+    /**
+     * FGAC 기반 인덱스 닫기: client.indices.close() 대응
+     */
+    async doFgacCloseIndex(index) {
+        const errScope = `doFgacCloseIndex(${index})`;
+        if (!index)
+            throw new Error(`.index(string) is required - ${errScope}`);
+        return this.proxy.doProxy('POST', index, `_close`);
+    }
+    /**
+     * FGAC 기반 인덱스 열기: client.indices.open() 대응
+     */
+    async doFgacOpenIndex(index) {
+        const errScope = `doFgacOpenIndex(${index})`;
+        if (!index)
+            throw new Error(`.index(string) is required - ${errScope}`);
+        return this.proxy.doProxy('POST', index, `_open`);
+    }
+}
+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.AbstractOS2Instance {
+    fgac;
+    /**
+     * 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,
+            autocompleteFields,
+            roleName,
+            userName,
+            idName: idName === null ? undefined : idName ?? '$id',
+        });
+        if (endpoint && indexName) {
+            this.fgac = new OS2FGACManager(options);
+            this.elastic = new OS2Service(options, this.fgac);
+            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;
+        return this.elastic.options;
+    }
+    get $X2() {
+        return $X2;
+    }
+    /**
+     * search
+     */
+    async search(body, params) {
+        if (!this.elastic)
+            throw new Error(`Could not read Elasticsearch endpoint or index setting.`);
+        const searchType = params?.searchType;
+        const elastic = this.elastic;
+        return elastic.search(body, searchType);
+    }
+    /** synchronize dynamo contents to os2  */
+    async synchronizeContents(options) {
+        const stopOnError = options?.stopOnError ?? false;
+        const filter = null;
+        // STEP 1. get source items
+        const dynamoOptions = {
+            tableName: engine_1.$U.env('MY_DYNAMO_TABLE', ''),
+            idName: '_id',
+        };
+        const $scan = new cores_2.DynamoScanService(dynamoOptions);
+        const { limit } = (0, commons_1.parsePaginateParam)(options);
+        // STEP 2. get role model
+        const indexName = this.options.indexName;
+        //* runs in parallel
+        const _parrallel = async (list, $res) => {
+            const items = await (0, helpers_1.my_parrallel)(list, async (N) => {
+                const id = N._id ?? N.id;
+                try {
+                    const stereo = commons_1.$T.S2(N?.stereo);
+                    if (!stereo || !stereo?.startsWith('#')) {
+                        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                        const { _id, ...rest } = N;
+                        await this.fgac.doFgacSave({ index: indexName, id, body: rest });
+                        return { id, error: null };
+                    }
+                    return { id };
+                }
+                catch (error) {
+                    if (stopOnError && $res) {
+                        (0, engine_1._err)(NS, `> error[${id}] =`, error);
+                        $res.last = null;
+                    }
+                    return { id, error: (0, test_helper_1.GETERR)(error) };
+                }
+            });
+            return items;
+        };
+        // runs with bulk
+        const _bulks = async (list, $res) => {
+            const body = list
+                .map(N => {
+                const _id = N._id ?? N.id;
+                const stereo = commons_1.$T.S2(N?.stereo);
+                if (!stereo || !stereo?.startsWith('#')) {
+                    return { ...N, _id };
+                }
+                return null;
+            })
+                .filter(N => !!N);
+            // not supported autocomplete options
+            const items = await this.fgac.doFgacBulk({ index: indexName, body });
+            return items?.map((N) => N?.index ?? N?.create);
+        };
+        // STEP 3. migrate items using doFgacSave
+        let last = null;
+        const results = [];
+        const _preprocessItems = (items) => {
+            return items.filter(item => {
+                const stereo = commons_1.$T.S2(item?.stereo);
+                return !(stereo && stereo.startsWith('#'));
+            });
+        };
+        while (true) {
+            if (last)
+                (0, engine_1._inf)(NS, `> last =`, engine_1.$U.json(last));
+            const $res = await $scan.scan(limit, last, filter);
+            const list = _preprocessItems($res?.list) ?? [];
+            // const items = await _parrallel(list, $res);
+            const res = await this.bulkItems(list, { idName: '_id' });
+            const failedItems = res?.failedItems ?? [];
+            (0, engine_1._log)(NS, `>> len =`, failedItems?.length ?? '-');
+            // 실패 ID + 메시지를 Map으로 생성
+            const failedMap = failedItems.reduce((map, f) => {
+                const id = f.item?._id || f.item?.id;
+                const reason = f.reason || f.item?.error?.reason || 'Unknown error';
+                if (id) {
+                    map.set(id, reason);
+                }
+                return map;
+            }, new Map());
+            // error 정보가 있는 경우 item에 추가
+            const itemsWithError = list.map(item => {
+                const id = item._id ?? item.id;
+                const error = id && failedMap.has(id) ? failedMap.get(id) : undefined;
+                return error ? { ...item, error } : item;
+            });
+            results.push(...itemsWithError);
+            if (!$res?.last?._id)
+                break;
+            last = $res?.last;
+        }
+        const total = results.length;
+        const failed = results.filter(N => !!N.error);
+        return { index: indexName, total, failed };
+    }
+    /** bulk items with auto-complete options */
+    async bulkItems(items, options) {
+        return this.elastic.bulkItems(items, options);
+    }
+}
+exports.OS2Instance = OS2Instance;
+/**
+ * internal tools
+ */
+const $X2 = {
+    /** describe endpoint-url into component */
+    describeEndpointUrl: (url, options) => {
+        const errScope = options?.errScope ?? `describeEndpointUrl()`;
+        const throwable = options?.throwable ?? true;
+        url = /^\/\/[a-z0-9]+/.test(url) ? `https:${url}` : url;
+        if (throwable) {
+            if (!url)
+                throw new Error(`@url(string) is required - ${errScope}`);
+            if (!(url?.startsWith('http://') || url?.startsWith('https://')))
+                throw new Error(`@url[${url ?? ''}] is invalid (no http) - ${errScope}`);
+        }
+        const $url = new URL(url);
+        const host = engine_1.$U.S($url.hostname || $url.host);
+        const isTunnel = $url.hostname === 'localhost';
+        const protocol = engine_1.$U.S($url.protocol).split(':')[0] ?? '';
+        const port = engine_1.$U.N($url.port, url?.startsWith('https') ? 443 : 80);
+        const hosts = host.split('.');
+        const isProxy = host.endsWith('.amazonaws.com') && hosts[hosts.length - 4] == 'execute-api';
+        const region = isProxy ? hosts[hosts.length - 3] : undefined;
+        return {
+            protocol,
+            host,
+            port,
+            region,
+            isTunnel,
+            isProxy,
+        };
+    },
+    /** load local credentials (for dev) */
+    loadCredentials: async (profile) => {
+        const errScope = `loadCredentials(${profile ?? ''})`;
+        const _profile = (name) => {
+            if (typeof name === 'string')
+                return name ? name : null;
+            const NAME = engine_1.$U.env('NAME', '');
+            return NAME && NAME !== 'none' ? NAME : null;
+        };
+        profile = _profile(profile);
+        const credentials = await (0, tools_1.asyncCredentials)(profile);
+        if (!credentials?.accessKeyId)
+            throw new Error(`@profile[${profile ?? ''}] is invalid - ${errScope}`);
+        return credentials;
+    },
+};
+/**
+ * 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() {
+            const endpoint = options?.endpoint ?? engine_1.$U.env('OS2_ENDPOINT', '');
+            const indexName = options?.indexName ?? engine_1.$U.env('OS2_INDEX', 'test-x1');
+            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;
+            super({
+                endpoint,
+                indexName,
+                tableName,
+                autocompleteFields,
+                roleName,
+                userName,
+            });
+        }
+        /**
+         * expose the internal helpers. (ONLY for debugging)
+         */
+        get $X2() {
+            return $X2;
+        }
+    })();
+};
+exports._OS2 = _OS2;
+/**
+ * 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.$OS2;
+//# sourceMappingURL=abstract-services.js.map