@things-factory/headless-twin 10.0.4 → 10.0.6

package/dist-server/service/twin-journal/twin-journal-query.js

@@ -6,7 +6,9 @@ const typeorm_1 = require("typeorm");
 const type_graphql_1 = require("type-graphql");
 const shell_1 = require("@things-factory/shell");
 const twin_event_js_1 = require("../twin-event/twin-event.js");
+const twin_event_type_js_1 = require("../twin-event/twin-event-type.js");
 const index_js_1 = require("../../engine/index.js");
+const kpi_query_js_1 = require("../../engine/kpi-query.js");
 /*
  * 저널 읽기 채널 — 상향 query.
  * twinEvents : append-only 이벤트 저널 조회(Ledger/History/Entity360) — instanceId·revision 범위·eventType 필터.
@@ -30,6 +32,96 @@ let TwinJournalQuery = class TwinJournalQuery {
         /* 최신순(DESC) 기본 — Ledger/recent 뷰. 범위 필터로 시간여행 구간 조회도 가능. */
         return (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).find({ where, order: { revision: 'DESC' }, take: limit ?? 200 });
     }
+    /**
+     * 저널 목록 — things-factory 표준 목록 계약(`ListParam` → `{ items, total }`).
+     *
+     * ── 왜 `twinEvents` 와 따로 두는가 ─────────────────────────────────────────
+     * `twinEvents` 는 배열만 돌려준다. 화면은 자기가 받은 게 전부인지 잘린 건지 알 수 없었고, 그래서
+     * 리스트가 **조용히 잘린 채 "이게 전부" 처럼** 보였다(원장 limit 120 이 대표적). 총건수를 함께
+     * 주면 "48 / 12,904" 라고 말할 수 있고, 사용자는 좁혀야 한다는 사실을 안다.
+     * 기존 호출자를 깨지 않으려고 `twinEvents` 는 그대로 두고 목록 계약을 새로 연다.
+     *
+     * ── 검색이 진짜인 이유 ─────────────────────────────────────────────────────
+     * `searchables` 는 전부 **인덱스 가능한 승격 컬럼**이다(payload JSON 안이 아니라). 프레임워크
+     * 질의 빌더는 `searchables` 에 없는 컬럼의 LIKE 를 경고 후 무시한다 — 인덱스 없는 전체 스캔을
+     * 막기 위해서다. 그 규율에 맞추려고 검색 축을 컬럼으로 승격했다(`twin-event-keys.ts`).
+     *
+     * 정렬 기본값은 revision DESC(최신순) — 저널의 자연 순서이자 ix_twin_event_0 가 그대로 타는 축.
+     */
+    async twinEventList(params, context, instanceId, spaceId) {
+        const { domain } = context.state;
+        if (!instanceId && !spaceId)
+            throw new Error('either instanceId or spaceId is required');
+        /* 테넌트 격리 — twinKpi 와 같은 규약. 남의 트윈은 빈 결과가 아니라 명시 실패로 알린다
+         * (조용한 빈 목록은 "권한 없음" 과 "데이터 없음" 을 구분할 수 없게 만든다). */
+        if (instanceId && !index_js_1.TwinEngine.owns(domain.id, instanceId)) {
+            throw new Error(`twin instance not found in this tenant: ${instanceId}`);
+        }
+        /* 대상 해소는 KPI 와 같은 창구를 쓴다 — 같은 공간을 보면서 화면마다 대상이 달라지면 안 된다. */
+        const instanceIds = await (0, kpi_query_js_1.resolveTwinTargets)(domain.id, instanceId, spaceId);
+        if (instanceIds.length === 0)
+            return { items: [], total: 0 };
+        /* 페이지 상한 — 화면이 실수로(또는 악의로) 저널 전체를 한 번에 달라고 해도 서버가 버틴다. */
+        const limit = Math.min(params.pagination?.limit ?? 100, 500);
+        const effective = {
+            ...params,
+            pagination: { page: params.pagination?.page ?? 1, limit },
+            /* 기본 정렬은 시각 내림차순 — 여러 트윈을 합칠 때 공통 축은 revision(트윈별 카운터)이 아니라
+             * **시각**이다. revision 으로 섞으면 서로 다른 트윈의 무관한 카운터가 뒤엉킨다. */
+            sortings: params.sortings?.length ? params.sortings : [{ name: 'eventTime', desc: true }]
+        };
+        const qb = (0, shell_1.getQueryBuilderFromListParams)({
+            repository: (0, shell_1.getRepository)(twin_event_js_1.TwinEvent),
+            params: effective,
+            domain,
+            /* 전부 인덱스 가능한 승격 컬럼 — 자유 검색어는 서버가 이 축들로 펼친다. */
+            searchables: ['epc', 'orderId', 'locationId', 'moverId', 'bizStep', 'eventType'],
+            /* 정렬은 인덱스가 받쳐 주는 축으로만 — 큰 저널에서 임의 컬럼 정렬은 전체 정렬 스캔이다. */
+            sortables: ['eventTime', 'revision', 'eventType', 'bizStep'],
+            defaultLimit: 100,
+            maxLimit: 500
+        });
+        /* 대상 범위는 호출자가 필터로 빼먹을 수 있는 값이 아니다 — 계약상 필수라 여기서 강제한다. */
+        qb.andWhere(`${qb.alias}.instanceId IN (:...instanceIds)`, { instanceIds });
+        const [items, total] = await qb.getManyAndCount();
+        /* 다음 커서는 **이번 페이지의 마지막 행**에서 만든다. 페이지가 상한보다 짧으면 뒤가 없다. */
+        const axes = (0, shell_1.cursorSortings)(effective.sortings, 'id');
+        const nextCursor = items.length === limit ? (0, shell_1.buildNextCursor)(items[items.length - 1], axes) : undefined;
+        return { items, total, nextCursor };
+    }
+    /**
+     * 업무 KPI — 시간창 처리량·소요시간·자원 점유. 저널을 **접어서** 만든다(새 계측을 심지 않는다).
+     *
+     * `twinMetrics`(초당 이벤트 수 = 인프라 부하)와 **다른 것**이다: 이건 "지난 한 시간에 몇 건 처리했고
+     * 한 건에 얼마나 걸렸나" 다. 이름이 비슷해 헷갈리기 쉬우므로 설명에 명시한다.
+     *
+     * 완료된 작업의 **시작 이벤트가 창 앞에 있을 수 있어** 조회 구간을 창보다 앞으로 넓힌다(lookback).
+     * 그래도 못 찾은 것은 결과의 `unpaired` 로 드러난다 — 평균에서 조용히 빠지면 지표가 거짓이 된다.
+     */
+    async twinKpi(context, spaceId, instanceId, fromTime, toTime, windowMinutes, buckets, lookbackMinutes, groupBy, groupLimit, compareTo) {
+        /* 테넌트 격리 — 트윈 지정이면 소속을 확인한다. 공간 지정이면 대상 해소가 도메인 목록에서
+         * 이뤄지므로(computeTwinKpi) 남의 트윈이 섞이지 않는다. 조용한 빈 결과가 아니라 명시 실패. */
+        if (instanceId && !index_js_1.TwinEngine.owns(context.state.domain.id, instanceId)) {
+            throw new Error(`twin instance not found in this tenant: ${instanceId}`);
+        }
+        if (!instanceId && !spaceId)
+            throw new Error('either spaceId or instanceId is required');
+        /* 창 해소·조회·폴드는 `computeTwinKpi` 가 소유한다 — 같은 규칙을 AI 도구와 공유해야 한다
+         * (두 곳에 적으면 화면과 AI 가 다른 숫자를 말한다). */
+        return (0, kpi_query_js_1.computeTwinKpi)({
+            domainId: context.state.domain.id,
+            instanceId,
+            spaceId,
+            fromTime,
+            toTime,
+            windowMinutes,
+            buckets,
+            lookbackMinutes,
+            groupBy: groupBy,
+            groupLimit,
+            compareTo: compareTo
+        });
+    }
     async twinReplay(instanceId, untilRevision, untilTime, context) {
         return index_js_1.TwinEngine.recover(context.state.domain.id, instanceId, untilRevision ?? undefined, untilTime ?? undefined);
     }
@@ -53,6 +145,41 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:paramtypes", [String, Number, Number, String, Number, Object, String]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinJournalQuery.prototype, "twinEvents", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => twin_event_type_js_1.TwinEventList, {
+        description: 'List twin journal events with the standard list contract (filters, pagination, sortings) plus the total match count. ' +
+            'Scope is either one twin (instanceId) or a whole site (spaceId, which folds in every running operational twin co-located there, the same targets twinKpi uses) — one of the two is required. ' +
+            'Searchable fields are the columns promoted out of the payload: epc (item), orderId, locationId, moverId (equipment), bizStep, eventType. ' +
+            'Returns total so a caller can show an honest "shown of total" count instead of silently truncating a long journal. ' +
+            'Defaults to newest first (revision descending) and to a page of 100; limit is capped at 500 per page.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Args)(type => shell_1.ListParam)),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__param(2, (0, type_graphql_1.Arg)('instanceId', { nullable: true, description: 'Read one twin instance journal.' })),
+    tslib_1.__param(3, (0, type_graphql_1.Arg)('spaceId', { nullable: true, description: 'Read every running operational twin co-located in this space, merged on the shared time axis.' })),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [shell_1.ListParam, Object, String, String]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinJournalQuery.prototype, "twinEventList", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        description: 'Windowed business KPI folded from the event journal, for one space (every running twin in it, folded together — averaging per-twin percentiles would be wrong) or one twin: throughput (completed tasks / orders), lead / work / wait time distributions (p50·p90), and per-resource busy ratio. Distinct from twinMetrics, which reports infrastructure throughput (events per second). When toTime is omitted the window ends at the twin\'s own last recorded event time, not wall clock — a simulated twin lives on its own clock, so asking for \'the last hour\' in real time would always find nothing. The basis used is reported in window.basis. Pass groupBy (resource | taskKind | node | order | area) to break the same window down by that perspective — per-group numbers use the same rules as the totals, so group counts sum to the total, and groups beyond groupLimit are reported as groups.truncated (how many groups) and groups.truncatedTasks (how much work those groups held) rather than silently dropped. Pass compareTo (previous | yesterday) to fold the same-length window shifted back and get comparison.delta (current minus that window); when the comparison window has no records, comparison.measured is false and no delta is produced rather than reporting zero change. Passing groupBy together with compareTo crosses the two: each group carries prevTasks / deltaTasks / deltaWorkP50Ms, groups absent from the comparison window are flagged isNew (no delta, so growth is not implied), and groups that had work before but none now are returned in groups.disappeared so a stopped area is never silently missing from the table. Area breakdown needs board nodes to carry a parent area; when they do not, groups.note says so instead of implying there was no work. When the journal read hits its row cap, eventsCapped is true and every number is a lower bound — narrow the window and ask again rather than reading the smaller figures as a drop in performance. Completions are counted in the window they complete; starts are looked up before the window, and any completion whose start was not found is reported in `unpaired` rather than silently dropped.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Ctx)()),
+    tslib_1.__param(1, (0, type_graphql_1.Arg)('spaceId', { nullable: true })),
+    tslib_1.__param(2, (0, type_graphql_1.Arg)('instanceId', { nullable: true })),
+    tslib_1.__param(3, (0, type_graphql_1.Arg)('fromTime', { nullable: true })),
+    tslib_1.__param(4, (0, type_graphql_1.Arg)('toTime', { nullable: true })),
+    tslib_1.__param(5, (0, type_graphql_1.Arg)('windowMinutes', type => type_graphql_1.Int, { nullable: true })),
+    tslib_1.__param(6, (0, type_graphql_1.Arg)('buckets', type => type_graphql_1.Int, { nullable: true })),
+    tslib_1.__param(7, (0, type_graphql_1.Arg)('lookbackMinutes', type => type_graphql_1.Int, { nullable: true })),
+    tslib_1.__param(8, (0, type_graphql_1.Arg)('groupBy', { nullable: true })),
+    tslib_1.__param(9, (0, type_graphql_1.Arg)('groupLimit', type => type_graphql_1.Int, { nullable: true })),
+    tslib_1.__param(10, (0, type_graphql_1.Arg)('compareTo', { nullable: true })),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [Object, String, String, String, String, Number, Number, Number, String, Number, String]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinJournalQuery.prototype, "twinKpi", null);
 tslib_1.__decorate([
     (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
         nullable: true,

package/dist-server/service/twin-journal/twin-journal-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"twin-journal-query.js","sourceRoot":"","sources":["../../../server/service/twin-journal/twin-journal-query.ts"],"names":[],"mappings":"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","sourcesContent":["import { Between, LessThanOrEqual, MoreThanOrEqual } from 'typeorm'\nimport { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'\n\nimport { getRepository, ScalarObject } from '@things-factory/shell'\n\nimport { TwinEvent } from '../twin-event/twin-event.js'\nimport { TwinEngine } from '../../engine/index.js'\n\n/*\n * 저널 읽기 채널 — 상향 query.\n * twinEvents : append-only 이벤트 저널 조회(Ledger/History/Entity360) — instanceId·revision 범위·eventType 필터.\n * twinReplay : 내구 저널을 replay 해 상태 재구성(재부팅 복구·시간여행) — untilRevision 으로 임의 과거.\n * (실시간 스트림은 twinState subscription, 명령은 twin-control mutation. 이건 '질의' 표면.)\n */\n@Resolver()\nexport class TwinJournalQuery {\n  @Query(returns => [TwinEvent], {\n    description: 'Read the append-only twin event journal (Ledger / History / audit), filtered and ordered by revision.'\n  })\n  async twinEvents(\n    @Arg('instanceId') instanceId: string,\n    @Arg('fromRevision', type => Int, { nullable: true }) fromRevision: number,\n    @Arg('toRevision', type => Int, { nullable: true }) toRevision: number,\n    @Arg('eventType', { nullable: true }) eventType: string,\n    @Arg('limit', type => Int, { nullable: true }) limit: number,\n    @Ctx() context: ResolverContext,\n    @Arg('untilTime', { nullable: true }) untilTime?: string\n  ): Promise<TwinEvent[]> {\n    const where: any = { domain: { id: context.state.domain.id }, instanceId }\n    if (eventType) where.eventType = eventType\n    /* 시각 커서(untilTime, ISO) 우선 — eventTime ≤ T(공유 clock). eventTime 은 ISO 문자열 컬럼이라 lexicographic 비교 성립. */\n    if (untilTime != null) where.eventTime = LessThanOrEqual(untilTime)\n    else if (fromRevision != null && toRevision != null) where.revision = Between(fromRevision, toRevision)\n    else if (fromRevision != null) where.revision = MoreThanOrEqual(fromRevision)\n    else if (toRevision != null) where.revision = LessThanOrEqual(toRevision)\n\n    /* 최신순(DESC) 기본 — Ledger/recent 뷰. 범위 필터로 시간여행 구간 조회도 가능. */\n    return getRepository(TwinEvent).find({ where, order: { revision: 'DESC' }, take: limit ?? 200 })\n  }\n\n  @Query(returns => ScalarObject, {\n    nullable: true,\n    description: 'Reconstruct twin state from the durable journal (DB → replay). untilTime (ISO) for time-travel on the shared clock (preferred); untilRevision for the lens-internal counter; omit both for latest.'\n  })\n  async twinReplay(\n    @Arg('instanceId') instanceId: string,\n    @Arg('untilRevision', type => Int, { nullable: true }) untilRevision: number,\n    @Arg('untilTime', { nullable: true }) untilTime: string,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    return TwinEngine.recover(context.state.domain.id, instanceId, untilRevision ?? undefined, untilTime ?? undefined)\n  }\n\n  @Query(returns => ScalarObject, {\n    description: 'Event time range (min/max ISO) across all co-located twins of a space — the history scrubber time axis.'\n  })\n  async twinTimeRange(\n    @Arg('spaceId') spaceId: string,\n    @Ctx() context: ResolverContext\n  ): Promise<{ minTime: string | null; maxTime: string | null }> {\n    return TwinEngine.timeRange(context.state.domain.id, spaceId)\n  }\n}\n"]}
+{"version":3,"file":"twin-journal-query.js","sourceRoot":"","sources":["../../../server/service/twin-journal/twin-journal-query.ts"],"names":[],"mappings":"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","sourcesContent":["import { Between, LessThanOrEqual, MoreThanOrEqual } from 'typeorm'\nimport { Arg, Args, Ctx, Int, Query, Resolver } from 'type-graphql'\n\nimport { buildNextCursor, cursorSortings, getQueryBuilderFromListParams, getRepository, ListParam, ScalarObject } from '@things-factory/shell'\n\nimport { TwinEvent } from '../twin-event/twin-event.js'\nimport { TwinEventList } from '../twin-event/twin-event-type.js'\nimport { TwinEngine } from '../../engine/index.js'\nimport { computeTwinKpi, resolveTwinTargets } from '../../engine/kpi-query.js'\n\n/*\n * 저널 읽기 채널 — 상향 query.\n * twinEvents : append-only 이벤트 저널 조회(Ledger/History/Entity360) — instanceId·revision 범위·eventType 필터.\n * twinReplay : 내구 저널을 replay 해 상태 재구성(재부팅 복구·시간여행) — untilRevision 으로 임의 과거.\n * (실시간 스트림은 twinState subscription, 명령은 twin-control mutation. 이건 '질의' 표면.)\n */\n@Resolver()\nexport class TwinJournalQuery {\n  @Query(returns => [TwinEvent], {\n    description: 'Read the append-only twin event journal (Ledger / History / audit), filtered and ordered by revision.'\n  })\n  async twinEvents(\n    @Arg('instanceId') instanceId: string,\n    @Arg('fromRevision', type => Int, { nullable: true }) fromRevision: number,\n    @Arg('toRevision', type => Int, { nullable: true }) toRevision: number,\n    @Arg('eventType', { nullable: true }) eventType: string,\n    @Arg('limit', type => Int, { nullable: true }) limit: number,\n    @Ctx() context: ResolverContext,\n    @Arg('untilTime', { nullable: true }) untilTime?: string\n  ): Promise<TwinEvent[]> {\n    const where: any = { domain: { id: context.state.domain.id }, instanceId }\n    if (eventType) where.eventType = eventType\n    /* 시각 커서(untilTime, ISO) 우선 — eventTime ≤ T(공유 clock). eventTime 은 ISO 문자열 컬럼이라 lexicographic 비교 성립. */\n    if (untilTime != null) where.eventTime = LessThanOrEqual(untilTime)\n    else if (fromRevision != null && toRevision != null) where.revision = Between(fromRevision, toRevision)\n    else if (fromRevision != null) where.revision = MoreThanOrEqual(fromRevision)\n    else if (toRevision != null) where.revision = LessThanOrEqual(toRevision)\n\n    /* 최신순(DESC) 기본 — Ledger/recent 뷰. 범위 필터로 시간여행 구간 조회도 가능. */\n    return getRepository(TwinEvent).find({ where, order: { revision: 'DESC' }, take: limit ?? 200 })\n  }\n\n  /**\n   * 저널 목록 — things-factory 표준 목록 계약(`ListParam` → `{ items, total }`).\n   *\n   * ── 왜 `twinEvents` 와 따로 두는가 ─────────────────────────────────────────\n   * `twinEvents` 는 배열만 돌려준다. 화면은 자기가 받은 게 전부인지 잘린 건지 알 수 없었고, 그래서\n   * 리스트가 **조용히 잘린 채 \"이게 전부\" 처럼** 보였다(원장 limit 120 이 대표적). 총건수를 함께\n   * 주면 \"48 / 12,904\" 라고 말할 수 있고, 사용자는 좁혀야 한다는 사실을 안다.\n   * 기존 호출자를 깨지 않으려고 `twinEvents` 는 그대로 두고 목록 계약을 새로 연다.\n   *\n   * ── 검색이 진짜인 이유 ─────────────────────────────────────────────────────\n   * `searchables` 는 전부 **인덱스 가능한 승격 컬럼**이다(payload JSON 안이 아니라). 프레임워크\n   * 질의 빌더는 `searchables` 에 없는 컬럼의 LIKE 를 경고 후 무시한다 — 인덱스 없는 전체 스캔을\n   * 막기 위해서다. 그 규율에 맞추려고 검색 축을 컬럼으로 승격했다(`twin-event-keys.ts`).\n   *\n   * 정렬 기본값은 revision DESC(최신순) — 저널의 자연 순서이자 ix_twin_event_0 가 그대로 타는 축.\n   */\n  @Query(returns => TwinEventList, {\n    description:\n      'List twin journal events with the standard list contract (filters, pagination, sortings) plus the total match count. ' +\n      'Scope is either one twin (instanceId) or a whole site (spaceId, which folds in every running operational twin co-located there, the same targets twinKpi uses) — one of the two is required. ' +\n      'Searchable fields are the columns promoted out of the payload: epc (item), orderId, locationId, moverId (equipment), bizStep, eventType. ' +\n      'Returns total so a caller can show an honest \"shown of total\" count instead of silently truncating a long journal. ' +\n      'Defaults to newest first (revision descending) and to a page of 100; limit is capped at 500 per page.'\n  })\n  async twinEventList(\n    @Args(type => ListParam) params: ListParam,\n    @Ctx() context: ResolverContext,\n    @Arg('instanceId', { nullable: true, description: 'Read one twin instance journal.' }) instanceId?: string,\n    @Arg('spaceId', { nullable: true, description: 'Read every running operational twin co-located in this space, merged on the shared time axis.' }) spaceId?: string\n  ): Promise<TwinEventList> {\n    const { domain } = context.state\n    if (!instanceId && !spaceId) throw new Error('either instanceId or spaceId is required')\n    /* 테넌트 격리 — twinKpi 와 같은 규약. 남의 트윈은 빈 결과가 아니라 명시 실패로 알린다\n     * (조용한 빈 목록은 \"권한 없음\" 과 \"데이터 없음\" 을 구분할 수 없게 만든다). */\n    if (instanceId && !TwinEngine.owns(domain.id, instanceId)) {\n      throw new Error(`twin instance not found in this tenant: ${instanceId}`)\n    }\n\n    /* 대상 해소는 KPI 와 같은 창구를 쓴다 — 같은 공간을 보면서 화면마다 대상이 달라지면 안 된다. */\n    const instanceIds = await resolveTwinTargets(domain.id, instanceId, spaceId)\n    if (instanceIds.length === 0) return { items: [], total: 0 }\n\n    /* 페이지 상한 — 화면이 실수로(또는 악의로) 저널 전체를 한 번에 달라고 해도 서버가 버틴다. */\n    const limit = Math.min(params.pagination?.limit ?? 100, 500)\n    const effective: ListParam = {\n      ...params,\n      pagination: { page: params.pagination?.page ?? 1, limit },\n      /* 기본 정렬은 시각 내림차순 — 여러 트윈을 합칠 때 공통 축은 revision(트윈별 카운터)이 아니라\n       * **시각**이다. revision 으로 섞으면 서로 다른 트윈의 무관한 카운터가 뒤엉킨다. */\n      sortings: params.sortings?.length ? params.sortings : [{ name: 'eventTime', desc: true }]\n    }\n\n    const qb = getQueryBuilderFromListParams({\n      repository: getRepository(TwinEvent),\n      params: effective,\n      domain,\n      /* 전부 인덱스 가능한 승격 컬럼 — 자유 검색어는 서버가 이 축들로 펼친다. */\n      searchables: ['epc', 'orderId', 'locationId', 'moverId', 'bizStep', 'eventType'],\n      /* 정렬은 인덱스가 받쳐 주는 축으로만 — 큰 저널에서 임의 컬럼 정렬은 전체 정렬 스캔이다. */\n      sortables: ['eventTime', 'revision', 'eventType', 'bizStep'],\n      defaultLimit: 100,\n      maxLimit: 500\n    })\n    /* 대상 범위는 호출자가 필터로 빼먹을 수 있는 값이 아니다 — 계약상 필수라 여기서 강제한다. */\n    qb.andWhere(`${qb.alias}.instanceId IN (:...instanceIds)`, { instanceIds })\n\n    const [items, total] = await qb.getManyAndCount()\n\n    /* 다음 커서는 **이번 페이지의 마지막 행**에서 만든다. 페이지가 상한보다 짧으면 뒤가 없다. */\n    const axes = cursorSortings(effective.sortings, 'id')\n    const nextCursor = items.length === limit ? buildNextCursor(items[items.length - 1], axes) : undefined\n\n    return { items, total, nextCursor }\n  }\n\n  /**\n   * 업무 KPI — 시간창 처리량·소요시간·자원 점유. 저널을 **접어서** 만든다(새 계측을 심지 않는다).\n   *\n   * `twinMetrics`(초당 이벤트 수 = 인프라 부하)와 **다른 것**이다: 이건 \"지난 한 시간에 몇 건 처리했고\n   * 한 건에 얼마나 걸렸나\" 다. 이름이 비슷해 헷갈리기 쉬우므로 설명에 명시한다.\n   *\n   * 완료된 작업의 **시작 이벤트가 창 앞에 있을 수 있어** 조회 구간을 창보다 앞으로 넓힌다(lookback).\n   * 그래도 못 찾은 것은 결과의 `unpaired` 로 드러난다 — 평균에서 조용히 빠지면 지표가 거짓이 된다.\n   */\n  @Query(returns => ScalarObject, {\n    description:\n      'Windowed business KPI folded from the event journal, for one space (every running twin in it, folded together — averaging per-twin percentiles would be wrong) or one twin: throughput (completed tasks / orders), lead / work / wait time distributions (p50·p90), and per-resource busy ratio. Distinct from twinMetrics, which reports infrastructure throughput (events per second). When toTime is omitted the window ends at the twin\\'s own last recorded event time, not wall clock — a simulated twin lives on its own clock, so asking for \\'the last hour\\' in real time would always find nothing. The basis used is reported in window.basis. Pass groupBy (resource | taskKind | node | order | area) to break the same window down by that perspective — per-group numbers use the same rules as the totals, so group counts sum to the total, and groups beyond groupLimit are reported as groups.truncated (how many groups) and groups.truncatedTasks (how much work those groups held) rather than silently dropped. Pass compareTo (previous | yesterday) to fold the same-length window shifted back and get comparison.delta (current minus that window); when the comparison window has no records, comparison.measured is false and no delta is produced rather than reporting zero change. Passing groupBy together with compareTo crosses the two: each group carries prevTasks / deltaTasks / deltaWorkP50Ms, groups absent from the comparison window are flagged isNew (no delta, so growth is not implied), and groups that had work before but none now are returned in groups.disappeared so a stopped area is never silently missing from the table. Area breakdown needs board nodes to carry a parent area; when they do not, groups.note says so instead of implying there was no work. When the journal read hits its row cap, eventsCapped is true and every number is a lower bound — narrow the window and ask again rather than reading the smaller figures as a drop in performance. Completions are counted in the window they complete; starts are looked up before the window, and any completion whose start was not found is reported in `unpaired` rather than silently dropped.'\n  })\n  async twinKpi(\n    @Ctx() context: ResolverContext,\n    /* 공간이 사용자의 단위다 — 한 트윈만 보려면 instanceId 를 준다(둘 중 하나 필수). */\n    @Arg('spaceId', { nullable: true }) spaceId?: string,\n    @Arg('instanceId', { nullable: true }) instanceId?: string,\n    /** 창 시작·끝(ISO). 미지정이면 최근 1시간. */\n    @Arg('fromTime', { nullable: true }) fromTime?: string,\n    @Arg('toTime', { nullable: true }) toTime?: string,\n    /** 창 길이(분). fromTime 이 있으면 무시. 기본 60. */\n    @Arg('windowMinutes', type => Int, { nullable: true }) windowMinutes?: number,\n    /** 추세를 위해 창을 N 등분(1~48). 미지정이면 쪼개지 않는다. */\n    @Arg('buckets', type => Int, { nullable: true }) buckets?: number,\n    /** 시작 이벤트를 찾기 위해 창보다 앞으로 더 읽는 시간(분). 기본 60. */\n    @Arg('lookbackMinutes', type => Int, { nullable: true }) lookbackMinutes?: number,\n    /** 관점 축 — 같은 창을 자원별·작업종류별·도착지점별·오더별·구역별로 쪼갠다. */\n    @Arg('groupBy', { nullable: true }) groupBy?: string,\n    /** 축의 상한(기본 20, 최대 100). 넘치면 잘라내고 잘린 수를 알린다. */\n    @Arg('groupLimit', type => Int, { nullable: true }) groupLimit?: number,\n    /** 비교 기준 — 같은 길이의 앞 구간(previous)이나 하루 전 같은 시간(yesterday). */\n    @Arg('compareTo', { nullable: true }) compareTo?: string\n  ): Promise<any> {\n    /* 테넌트 격리 — 트윈 지정이면 소속을 확인한다. 공간 지정이면 대상 해소가 도메인 목록에서\n     * 이뤄지므로(computeTwinKpi) 남의 트윈이 섞이지 않는다. 조용한 빈 결과가 아니라 명시 실패. */\n    if (instanceId && !TwinEngine.owns(context.state.domain.id, instanceId)) {\n      throw new Error(`twin instance not found in this tenant: ${instanceId}`)\n    }\n    if (!instanceId && !spaceId) throw new Error('either spaceId or instanceId is required')\n    /* 창 해소·조회·폴드는 `computeTwinKpi` 가 소유한다 — 같은 규칙을 AI 도구와 공유해야 한다\n     * (두 곳에 적으면 화면과 AI 가 다른 숫자를 말한다). */\n    return computeTwinKpi({\n      domainId: context.state.domain.id,\n      instanceId,\n      spaceId,\n      fromTime,\n      toTime,\n      windowMinutes,\n      buckets,\n      lookbackMinutes,\n      groupBy: groupBy as any,\n      groupLimit,\n      compareTo: compareTo as any\n    })\n  }\n\n  @Query(returns => ScalarObject, {\n    nullable: true,\n    description: 'Reconstruct twin state from the durable journal (DB → replay). untilTime (ISO) for time-travel on the shared clock (preferred); untilRevision for the lens-internal counter; omit both for latest.'\n  })\n  async twinReplay(\n    @Arg('instanceId') instanceId: string,\n    @Arg('untilRevision', type => Int, { nullable: true }) untilRevision: number,\n    @Arg('untilTime', { nullable: true }) untilTime: string,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    return TwinEngine.recover(context.state.domain.id, instanceId, untilRevision ?? undefined, untilTime ?? undefined)\n  }\n\n  @Query(returns => ScalarObject, {\n    description: 'Event time range (min/max ISO) across all co-located twins of a space — the history scrubber time axis.'\n  })\n  async twinTimeRange(\n    @Arg('spaceId') spaceId: string,\n    @Ctx() context: ResolverContext\n  ): Promise<{ minTime: string | null; maxTime: string | null }> {\n    return TwinEngine.timeRange(context.state.domain.id, spaceId)\n  }\n}\n"]}