@things-factory/headless-twin 10.0.12 → 10.0.13

package/dist-server/service/twin-ingest-window/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installIngestWindowWriter = exports.resolvers = exports.entities = void 0;
+const twin_ingest_window_js_1 = require("./twin-ingest-window.js");
+const twin_ingest_window_query_js_1 = require("./twin-ingest-window-query.js");
+exports.entities = [twin_ingest_window_js_1.TwinIngestWindow];
+exports.resolvers = [twin_ingest_window_query_js_1.TwinIngestWindowQuery];
+var twin_ingest_window_writer_js_1 = require("./twin-ingest-window-writer.js");
+Object.defineProperty(exports, "installIngestWindowWriter", { enumerable: true, get: function () { return twin_ingest_window_writer_js_1.installIngestWindowWriter; } });
+//# sourceMappingURL=index.js.map

package/dist-server/service/twin-ingest-window/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/service/twin-ingest-window/index.ts"],"names":[],"mappings":";;;AAAA,mEAA0D;AAC1D,+EAAqE;AAExD,QAAA,QAAQ,GAAG,CAAC,wCAAgB,CAAC,CAAA;AAC7B,QAAA,SAAS,GAAG,CAAC,mDAAqB,CAAC,CAAA;AAEhD,+EAA0E;AAAjE,yIAAA,yBAAyB,OAAA","sourcesContent":["import { TwinIngestWindow } from './twin-ingest-window.js'\nimport { TwinIngestWindowQuery } from './twin-ingest-window-query.js'\n\nexport const entities = [TwinIngestWindow]\nexport const resolvers = [TwinIngestWindowQuery]\n\nexport { installIngestWindowWriter } from './twin-ingest-window-writer.js'\n"]}

package/dist-server/service/twin-ingest-window/twin-ingest-window-query.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 한 번에 돌려주는 창 수 상한 — 144창 × 10분 = 24시간.
+ *
+ * 상한이 필요한 이유는 이 표가 **자란다**는 것이다(트윈 1,000개에 하루 14.4만 행). 상한에서 밀려난
+ * 수는 **세어서 낸다** — 조용히 자르면 화면이 「그 앞에는 아무 일도 없었다」로 읽는다.
+ */
+export declare const HISTORY_WINDOW_LIMIT = 144;
+/** 물을 수 있는 기간의 상한(시간). 넘겨도 여기서 자르고, 자른 사실을 낸다. */
+export declare const HISTORY_HOURS_MAX = 168;
+export declare class TwinIngestWindowQuery {
+    twinIngestHistory(instanceId: string, hours: number | undefined, context: ResolverContext): Promise<any>;
+}

package/dist-server/service/twin-ingest-window/twin-ingest-window-query.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinIngestWindowQuery = exports.HISTORY_HOURS_MAX = exports.HISTORY_WINDOW_LIMIT = void 0;
+const tslib_1 = require("tslib");
+const type_graphql_1 = require("type-graphql");
+const typeorm_1 = require("typeorm");
+const shell_1 = require("@things-factory/shell");
+const index_js_1 = require("../../engine/index.js");
+const twin_ingest_window_js_1 = require("./twin-ingest-window.js");
+/*
+ * 인제스트 창 **이력** — 재기동 뒤에도 추이를 이어 본다.
+ *
+ * ── 왜 따로 있나 (2026-08-20) ───────────────────────────────────────────────
+ * 창을 표로 남기기 시작했는데 **읽는 코드가 없었다.** 21행이 쌓여 있고 아무도 보지 않았다 — 이
+ * 프로젝트가 결함으로 보는 상태다(「필드만 만들고 아무도 읽지 않는다」). 표를 만든 이유가 「메모리
+ * 장부는 재기동에 사라지고 6시간까지인데 추이는 그보다 오래 봐야 한다」였으니, 목적이 미완이었다.
+ *
+ * ── 왜 `twinIngestHealth` 에 합치지 않나 ────────────────────────────────────
+ * 그 조회는 **화면이 자주 묻는다**(상세를 열 때마다, 목록은 응답에 요약이 함께 온다). 거기에 DB 주사를
+ * 얹으면 이 세션에서 없앤 것과 같은 종류의 비용이 돌아온다 — 자주 묻는 조회가 자라는 표를 읽는 것.
+ * 이력은 **다른 질문**이고 덜 자주 묻는다: 「더 뒤까지 보여 달라」.
+ *
+ * ── 이어 붙이기는 서버가 한다 ───────────────────────────────────────────────
+ * 표와 메모리는 겹친다(프로세스가 살아 있는 동안 닫힌 창은 둘 다에 있다). 겹침을 화면이 정리하게 두면
+ * 화면마다 규칙이 갈리고, 같은 구간이 두 번 그려지거나 사라진다. 그래서 여기서 한 벌로 이어 붙이고
+ * **어디서부터 메모리인지**(`liveFrom`)를 함께 낸다 — 화면이 근거를 말할 수 있게.
+ */
+/**
+ * 한 번에 돌려주는 창 수 상한 — 144창 × 10분 = 24시간.
+ *
+ * 상한이 필요한 이유는 이 표가 **자란다**는 것이다(트윈 1,000개에 하루 14.4만 행). 상한에서 밀려난
+ * 수는 **세어서 낸다** — 조용히 자르면 화면이 「그 앞에는 아무 일도 없었다」로 읽는다.
+ */
+exports.HISTORY_WINDOW_LIMIT = 144;
+/** 물을 수 있는 기간의 상한(시간). 넘겨도 여기서 자르고, 자른 사실을 낸다. */
+exports.HISTORY_HOURS_MAX = 168;
+let TwinIngestWindowQuery = class TwinIngestWindowQuery {
+    async twinIngestHistory(instanceId, hours, context) {
+        const domainId = context.state.domain.id;
+        /* 테넌트 격리 — 멈춘 트윈의 이력도 볼 수 있어야 한다(그때가 가장 보고 싶은 때다). */
+        if (!index_js_1.TwinEngine.owns(domainId, instanceId) && !(await index_js_1.TwinEngine.ownsRegistered(domainId, instanceId)))
+            return null;
+        const asked = Number.isFinite(Number(hours)) && Number(hours) > 0 ? Math.floor(Number(hours)) : 24;
+        const span = Math.min(asked, exports.HISTORY_HOURS_MAX);
+        const now = Date.now();
+        const fromMs = now - span * 3_600_000;
+        /*
+         * 표에서 그 구간의 닫힌 창을 읽는다. **상한을 둔다** — 자라는 표이고, 이 조회가 화면에서 열린다.
+         * 최신 쪽이 중요하므로 내려서 정렬해 가져오고, 낼 때 다시 올린다.
+         */
+        const repo = (0, shell_1.getRepository)(twin_ingest_window_js_1.TwinIngestWindow);
+        const where = {
+            domain: { id: domainId },
+            instanceId,
+            closedAt: (0, typeorm_1.Between)(new Date(fromMs), new Date(now))
+        };
+        const rows = await repo.find({ where, order: { closedAt: 'DESC' }, take: exports.HISTORY_WINDOW_LIMIT });
+        /*
+         * 상한에 닿았으면 **몇 개가 밀렸는지 센다.** 「더 있음」만 말하면 화면이 그 앞을 짐작하게 된다.
+         * 상한에 닿지 않았으면 셀 필요가 없다(왕복을 아낀다).
+         */
+        const storedDropped = rows.length === exports.HISTORY_WINDOW_LIMIT ? Math.max(0, (await repo.count({ where })) - rows.length) : 0;
+        const stored = rows.reverse().map(r => ({
+            from: r.openedAt?.toISOString?.() ?? new Date(r.openedAt).toISOString(),
+            to: r.closedAt?.toISOString?.() ?? new Date(r.closedAt).toISOString(),
+            offered: r.offered,
+            /* 통과는 **트윈에 닿은** 것만. 표의 값을 그대로 쓴다 — 읽는 쪽에서 다시 나누면 반올림이 갈린다. */
+            accepted: r.offered - r.rejected - (r.undelivered ?? 0),
+            rejected: r.rejected,
+            undelivered: r.undelivered ?? 0,
+            acceptedRatio: typeof r.acceptedRatio === 'number' ? r.acceptedRatio : null,
+            rows: r.journaledRows ?? 0,
+            flushes: r.journalFlushes ?? 0,
+            source: 'stored'
+        }));
+        /* 메모리 장부의 닫힌 창 — 이쪽이 최신이고, 겹치는 구간은 이쪽을 쓴다(같은 사실의 원본이다). */
+        const live = (index_js_1.TwinEngine.ingestHealthOf(domainId, instanceId).trend ?? []).map((w) => ({
+            ...w,
+            source: 'live'
+        }));
+        /*
+         * 겹침 정리 — 창의 **여는 시각**이 키다. 같은 창이 표와 메모리에 둘 다 있으면 하나만 낸다.
+         * 시각 문자열을 그대로 키로 쓰지 않는다: 드라이버가 밀리초를 자르거나 형식을 바꿀 수 있어
+         * 같은 창이 다른 키가 된다. epoch 로 견준다.
+         */
+        const liveStarts = new Set(live.map((w) => Date.parse(w.from)));
+        const windows = [...stored.filter(w => !liveStarts.has(Date.parse(w.from))), ...live];
+        return {
+            windows,
+            hours: span,
+            /* 물은 것보다 짧게 잘렸으면 밝힌다. */
+            ...(span < asked ? { hoursClamped: asked } : {}),
+            from: new Date(fromMs).toISOString(),
+            to: new Date(now).toISOString(),
+            /** 표에서 읽은 창 수 · 상한에서 밀려난 수. */
+            storedCount: stored.length,
+            storedDropped,
+            /**
+             * 어디서부터 메모리인가 — 화면이 근거를 말할 수 있게. 메모리에 닫힌 창이 없으면 `null` 이다
+             * (재기동 직후가 그렇다: 그때 보이는 것은 전부 표에서 온 것이다).
+             */
+            liveFrom: live.length ? live[0].from : null,
+            liveCount: live.length
+        };
+    }
+};
+exports.TwinIngestWindowQuery = TwinIngestWindowQuery;
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: 'Ingest windows for one twin over a past span, stitched from two sources so the trend survives a restart: closed windows persisted in the table (older) and the in-memory ledger (recent, roughly the last 6 hours). Overlap is resolved here rather than on screen — a window present in both is reported once, from memory, and `liveFrom` says where memory takes over so a screen can state its basis. Each window carries offered / accepted / rejected / undelivered plus the journal rows written and the write round-trips behind them; `acceptedRatio` is null when nothing was offered, because an empty window is not a perfect one. Deliberately separate from twinIngestHealth: that query is polled whenever a screen opens, and making it scan a growing table would reintroduce the cost this codebase just removed elsewhere. Counts that could not be returned are reported rather than dropped — `storedDropped` when the row cap was hit and `hoursClamped` when the requested span was longer than allowed. Null if the instance is not in the current domain.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Arg)('hours', type => type_graphql_1.Int, { nullable: true, description: 'How far back to read, in hours. Defaults to 24 and is clamped to 168.' })),
+    tslib_1.__param(2, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Number, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinIngestWindowQuery.prototype, "twinIngestHistory", null);
+exports.TwinIngestWindowQuery = TwinIngestWindowQuery = tslib_1.__decorate([
+    (0, type_graphql_1.Resolver)()
+], TwinIngestWindowQuery);
+//# sourceMappingURL=twin-ingest-window-query.js.map

package/dist-server/service/twin-ingest-window/twin-ingest-window-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-ingest-window-query.js","sourceRoot":"","sources":["../../../server/service/twin-ingest-window/twin-ingest-window-query.ts"],"names":[],"mappings":"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","sourcesContent":["import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'\nimport { Between } from 'typeorm'\n\nimport { ScalarObject, getRepository } from '@things-factory/shell'\n\nimport { TwinEngine } from '../../engine/index.js'\nimport { TwinIngestWindow } from './twin-ingest-window.js'\n\n/*\n * 인제스트 창 **이력** — 재기동 뒤에도 추이를 이어 본다.\n *\n * ── 왜 따로 있나 (2026-08-20) ───────────────────────────────────────────────\n * 창을 표로 남기기 시작했는데 **읽는 코드가 없었다.** 21행이 쌓여 있고 아무도 보지 않았다 — 이\n * 프로젝트가 결함으로 보는 상태다(「필드만 만들고 아무도 읽지 않는다」). 표를 만든 이유가 「메모리\n * 장부는 재기동에 사라지고 6시간까지인데 추이는 그보다 오래 봐야 한다」였으니, 목적이 미완이었다.\n *\n * ── 왜 `twinIngestHealth` 에 합치지 않나 ────────────────────────────────────\n * 그 조회는 **화면이 자주 묻는다**(상세를 열 때마다, 목록은 응답에 요약이 함께 온다). 거기에 DB 주사를\n * 얹으면 이 세션에서 없앤 것과 같은 종류의 비용이 돌아온다 — 자주 묻는 조회가 자라는 표를 읽는 것.\n * 이력은 **다른 질문**이고 덜 자주 묻는다: 「더 뒤까지 보여 달라」.\n *\n * ── 이어 붙이기는 서버가 한다 ───────────────────────────────────────────────\n * 표와 메모리는 겹친다(프로세스가 살아 있는 동안 닫힌 창은 둘 다에 있다). 겹침을 화면이 정리하게 두면\n * 화면마다 규칙이 갈리고, 같은 구간이 두 번 그려지거나 사라진다. 그래서 여기서 한 벌로 이어 붙이고\n * **어디서부터 메모리인지**(`liveFrom`)를 함께 낸다 — 화면이 근거를 말할 수 있게.\n */\n\n/**\n * 한 번에 돌려주는 창 수 상한 — 144창 × 10분 = 24시간.\n *\n * 상한이 필요한 이유는 이 표가 **자란다**는 것이다(트윈 1,000개에 하루 14.4만 행). 상한에서 밀려난\n * 수는 **세어서 낸다** — 조용히 자르면 화면이 「그 앞에는 아무 일도 없었다」로 읽는다.\n */\nexport const HISTORY_WINDOW_LIMIT = 144\n\n/** 물을 수 있는 기간의 상한(시간). 넘겨도 여기서 자르고, 자른 사실을 낸다. */\nexport const HISTORY_HOURS_MAX = 168\n\n@Resolver()\nexport class TwinIngestWindowQuery {\n  @Query(returns => ScalarObject, {\n    nullable: true,\n    description:\n      'Ingest windows for one twin over a past span, stitched from two sources so the trend survives a restart: closed windows persisted in the table (older) and the in-memory ledger (recent, roughly the last 6 hours). Overlap is resolved here rather than on screen — a window present in both is reported once, from memory, and `liveFrom` says where memory takes over so a screen can state its basis. Each window carries offered / accepted / rejected / undelivered plus the journal rows written and the write round-trips behind them; `acceptedRatio` is null when nothing was offered, because an empty window is not a perfect one. Deliberately separate from twinIngestHealth: that query is polled whenever a screen opens, and making it scan a growing table would reintroduce the cost this codebase just removed elsewhere. Counts that could not be returned are reported rather than dropped — `storedDropped` when the row cap was hit and `hoursClamped` when the requested span was longer than allowed. Null if the instance is not in the current domain.'\n  })\n  async twinIngestHistory(\n    @Arg('instanceId') instanceId: string,\n    @Arg('hours', type => Int, { nullable: true, description: 'How far back to read, in hours. Defaults to 24 and is clamped to 168.' })\n    hours: number | undefined,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const domainId = context.state.domain.id\n    /* 테넌트 격리 — 멈춘 트윈의 이력도 볼 수 있어야 한다(그때가 가장 보고 싶은 때다). */\n    if (!TwinEngine.owns(domainId, instanceId) && !(await TwinEngine.ownsRegistered(domainId, instanceId))) return null\n\n    const asked = Number.isFinite(Number(hours)) && Number(hours) > 0 ? Math.floor(Number(hours)) : 24\n    const span = Math.min(asked, HISTORY_HOURS_MAX)\n    const now = Date.now()\n    const fromMs = now - span * 3_600_000\n\n    /*\n     * 표에서 그 구간의 닫힌 창을 읽는다. **상한을 둔다** — 자라는 표이고, 이 조회가 화면에서 열린다.\n     * 최신 쪽이 중요하므로 내려서 정렬해 가져오고, 낼 때 다시 올린다.\n     */\n    const repo = getRepository(TwinIngestWindow)\n    const where = {\n      domain: { id: domainId } as any,\n      instanceId,\n      closedAt: Between(new Date(fromMs), new Date(now))\n    }\n    const rows = await repo.find({ where, order: { closedAt: 'DESC' }, take: HISTORY_WINDOW_LIMIT })\n\n    /*\n     * 상한에 닿았으면 **몇 개가 밀렸는지 센다.** 「더 있음」만 말하면 화면이 그 앞을 짐작하게 된다.\n     * 상한에 닿지 않았으면 셀 필요가 없다(왕복을 아낀다).\n     */\n    const storedDropped = rows.length === HISTORY_WINDOW_LIMIT ? Math.max(0, (await repo.count({ where })) - rows.length) : 0\n\n    const stored = rows.reverse().map(r => ({\n      from: r.openedAt?.toISOString?.() ?? new Date(r.openedAt as any).toISOString(),\n      to: r.closedAt?.toISOString?.() ?? new Date(r.closedAt as any).toISOString(),\n      offered: r.offered,\n      /* 통과는 **트윈에 닿은** 것만. 표의 값을 그대로 쓴다 — 읽는 쪽에서 다시 나누면 반올림이 갈린다. */\n      accepted: r.offered - r.rejected - (r.undelivered ?? 0),\n      rejected: r.rejected,\n      undelivered: r.undelivered ?? 0,\n      acceptedRatio: typeof r.acceptedRatio === 'number' ? r.acceptedRatio : null,\n      rows: r.journaledRows ?? 0,\n      flushes: r.journalFlushes ?? 0,\n      source: 'stored' as const\n    }))\n\n    /* 메모리 장부의 닫힌 창 — 이쪽이 최신이고, 겹치는 구간은 이쪽을 쓴다(같은 사실의 원본이다). */\n    const live = (TwinEngine.ingestHealthOf(domainId, instanceId).trend ?? []).map((w: any) => ({\n      ...w,\n      source: 'live' as const\n    }))\n\n    /*\n     * 겹침 정리 — 창의 **여는 시각**이 키다. 같은 창이 표와 메모리에 둘 다 있으면 하나만 낸다.\n     * 시각 문자열을 그대로 키로 쓰지 않는다: 드라이버가 밀리초를 자르거나 형식을 바꿀 수 있어\n     * 같은 창이 다른 키가 된다. epoch 로 견준다.\n     */\n    const liveStarts = new Set(live.map((w: any) => Date.parse(w.from)))\n    const windows = [...stored.filter(w => !liveStarts.has(Date.parse(w.from))), ...live]\n\n    return {\n      windows,\n      hours: span,\n      /* 물은 것보다 짧게 잘렸으면 밝힌다. */\n      ...(span < asked ? { hoursClamped: asked } : {}),\n      from: new Date(fromMs).toISOString(),\n      to: new Date(now).toISOString(),\n      /** 표에서 읽은 창 수 · 상한에서 밀려난 수. */\n      storedCount: stored.length,\n      storedDropped,\n      /**\n       * 어디서부터 메모리인가 — 화면이 근거를 말할 수 있게. 메모리에 닫힌 창이 없으면 `null` 이다\n       * (재기동 직후가 그렇다: 그때 보이는 것은 전부 표에서 온 것이다).\n       */\n      liveFrom: live.length ? live[0].from : null,\n      liveCount: live.length\n    }\n  }\n}\n"]}

package/dist-server/service/twin-ingest-window/twin-ingest-window-writer.d.ts

@@ -0,0 +1 @@
+export declare function installIngestWindowWriter(): void;

package/dist-server/service/twin-ingest-window/twin-ingest-window-writer.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installIngestWindowWriter = installIngestWindowWriter;
+const log_js_1 = require("../../engine/log.js");
+const shell_1 = require("@things-factory/shell");
+const index_js_1 = require("../../engine/index.js");
+const twin_ingest_window_js_1 = require("./twin-ingest-window.js");
+/*
+ * 닫힌 창을 표로 옮긴다 — **영속이 붙는 유일한 자리.**
+ *
+ * 커널 층(`engine/ingest-health.ts`)은 저장 계층을 모른다. 창이 닫힐 때 부를 곳을 엔진이 문으로 열어
+ * 두었고(`onIngestWindowClosed`), 이 파일이 부팅에서 한 번 등록한다. 그래서 기록 경로가 갈리지 않는다.
+ *
+ * ── 실패를 삼키지 않는다 ────────────────────────────────────────────────────
+ * 쓰기가 터져도 메모리 장부는 계속 굴러간다(`rollIngestWindow` 가 훅을 감싼다). 다만 **조용히 넘기지는
+ * 않는다** — 실패를 로그로 남긴다. 그러지 않으면 추이 표에 구멍이 생긴 이유를 나중에 알 수 없다.
+ *
+ * ── 왜 await 하지 않나 ──────────────────────────────────────────────────────
+ * 이 훅은 인제스트 경로에서 불린다(라이브 피드의 콜백 안). 여기서 DB 를 기다리면 **유입이 DB 속도에
+ * 묶인다** — 이 기능이 막으려던 부하가 그 모양으로 돌아온다. 그래서 띄워 보내고 결과만 로그로 받는다.
+ */
+function installIngestWindowWriter() {
+    index_js_1.TwinEngine.onIngestWindowClosed((at, closed) => {
+        const repo = (0, shell_1.getRepository)(twin_ingest_window_js_1.TwinIngestWindow);
+        const offered = closed.offered;
+        repo
+            .save(repo.create({
+            domain: { id: at.domainId },
+            instanceId: at.instanceId,
+            openedAt: new Date(closed.startMs),
+            closedAt: new Date(closed.endMs),
+            offered,
+            rejected: closed.rejected,
+            undelivered: closed.undelivered,
+            /* 적힌 것도 같은 행에 — 창이 유입 없이 닫혔어도(시뮬) 이 두 수는 사실이다. */
+            journaledRows: closed.rows,
+            journalFlushes: closed.flushes,
+            /*
+             * 제시가 0 이면 비워 둔다 — 1 로 채우면 「전부 통과」로 읽힌다.
+             * 통과는 **트윈에 닿은** 것만이다: 버려진 것을 빼지 않으면 멈춘 트윈의 창이 100% 로 남는다.
+             */
+            ...(offered > 0
+                ? { acceptedRatio: round4((offered - closed.rejected - closed.undelivered) / offered) }
+                : {})
+        }))
+            .catch(err => (0, log_js_1.twinWarn)(`[twin-ingest-window] "${at.instanceId}" window not persisted (trend will have a gap here):`, err?.message ?? err));
+    });
+}
+/** 0.999 가 1 로 반올림되면 「전부 통과」로 읽힌다 — 자릿수를 넉넉히 준다(메모리 장부와 같은 규칙). */
+const round4 = (v) => Math.round(v * 10000) / 10000;
+//# sourceMappingURL=twin-ingest-window-writer.js.map

package/dist-server/service/twin-ingest-window/twin-ingest-window-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-ingest-window-writer.js","sourceRoot":"","sources":["../../../server/service/twin-ingest-window/twin-ingest-window-writer.ts"],"names":[],"mappings":";;AAoBA,8DAiCC;AArDD,gDAA8C;AAC9C,iDAAqD;AAErD,oDAAkD;AAClD,mEAA0D;AAE1D;;;;;;;;;;;;;GAaG;AACH,SAAgB,yBAAyB;IACvC,qBAAU,CAAC,oBAAoB,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE;QAC7C,MAAM,IAAI,GAAG,IAAA,qBAAa,EAAC,wCAAgB,CAAC,CAAA;QAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;QAC9B,IAAI;aACD,IAAI,CACH,IAAI,CAAC,MAAM,CAAC;YACV,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAS;YAClC,UAAU,EAAE,EAAE,CAAC,UAAU;YACzB,QAAQ,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YAClC,QAAQ,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YAChC,OAAO;YACP,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,kDAAkD;YAClD,aAAa,EAAE,MAAM,CAAC,IAAI;YAC1B,cAAc,EAAE,MAAM,CAAC,OAAO;YAC9B;;;eAGG;YACH,GAAG,CAAC,OAAO,GAAG,CAAC;gBACb,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,EAAE;gBACvF,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CACH;aACA,KAAK,CAAC,GAAG,CAAC,EAAE,CACX,IAAA,iBAAQ,EACN,yBAAyB,EAAE,CAAC,UAAU,sDAAsD,EAC5F,GAAG,EAAE,OAAO,IAAI,GAAG,CACpB,CACF,CAAA;IACL,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,MAAM,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAA","sourcesContent":["import { twinWarn } from '../../engine/log.js'\nimport { getRepository } from '@things-factory/shell'\n\nimport { TwinEngine } from '../../engine/index.js'\nimport { TwinIngestWindow } from './twin-ingest-window.js'\n\n/*\n * 닫힌 창을 표로 옮긴다 — **영속이 붙는 유일한 자리.**\n *\n * 커널 층(`engine/ingest-health.ts`)은 저장 계층을 모른다. 창이 닫힐 때 부를 곳을 엔진이 문으로 열어\n * 두었고(`onIngestWindowClosed`), 이 파일이 부팅에서 한 번 등록한다. 그래서 기록 경로가 갈리지 않는다.\n *\n * ── 실패를 삼키지 않는다 ────────────────────────────────────────────────────\n * 쓰기가 터져도 메모리 장부는 계속 굴러간다(`rollIngestWindow` 가 훅을 감싼다). 다만 **조용히 넘기지는\n * 않는다** — 실패를 로그로 남긴다. 그러지 않으면 추이 표에 구멍이 생긴 이유를 나중에 알 수 없다.\n *\n * ── 왜 await 하지 않나 ──────────────────────────────────────────────────────\n * 이 훅은 인제스트 경로에서 불린다(라이브 피드의 콜백 안). 여기서 DB 를 기다리면 **유입이 DB 속도에\n * 묶인다** — 이 기능이 막으려던 부하가 그 모양으로 돌아온다. 그래서 띄워 보내고 결과만 로그로 받는다.\n */\nexport function installIngestWindowWriter(): void {\n  TwinEngine.onIngestWindowClosed((at, closed) => {\n    const repo = getRepository(TwinIngestWindow)\n    const offered = closed.offered\n    repo\n      .save(\n        repo.create({\n          domain: { id: at.domainId } as any,\n          instanceId: at.instanceId,\n          openedAt: new Date(closed.startMs),\n          closedAt: new Date(closed.endMs),\n          offered,\n          rejected: closed.rejected,\n          undelivered: closed.undelivered,\n          /* 적힌 것도 같은 행에 — 창이 유입 없이 닫혔어도(시뮬) 이 두 수는 사실이다. */\n          journaledRows: closed.rows,\n          journalFlushes: closed.flushes,\n          /*\n           * 제시가 0 이면 비워 둔다 — 1 로 채우면 「전부 통과」로 읽힌다.\n           * 통과는 **트윈에 닿은** 것만이다: 버려진 것을 빼지 않으면 멈춘 트윈의 창이 100% 로 남는다.\n           */\n          ...(offered > 0\n            ? { acceptedRatio: round4((offered - closed.rejected - closed.undelivered) / offered) }\n            : {})\n        })\n      )\n      .catch(err =>\n        twinWarn(\n          `[twin-ingest-window] \"${at.instanceId}\" window not persisted (trend will have a gap here):`,\n          err?.message ?? err\n        )\n      )\n  })\n}\n\n/** 0.999 가 1 로 반올림되면 「전부 통과」로 읽힌다 — 자릿수를 넉넉히 준다(메모리 장부와 같은 규칙). */\nconst round4 = (v: number) => Math.round(v * 10000) / 10000\n"]}

package/dist-server/service/twin-ingest-window/twin-ingest-window.d.ts

@@ -0,0 +1,16 @@
+import { Domain } from '@things-factory/shell';
+export declare class TwinIngestWindow {
+    readonly id: string;
+    domain?: Domain;
+    domainId?: string;
+    instanceId: string;
+    openedAt: Date;
+    closedAt: Date;
+    offered: number;
+    rejected: number;
+    undelivered: number;
+    acceptedRatio?: number;
+    journaledRows: number;
+    journalFlushes: number;
+    createdAt?: Date;
+}

package/dist-server/service/twin-ingest-window/twin-ingest-window.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinIngestWindow = void 0;
+const tslib_1 = require("tslib");
+const typeorm_1 = require("typeorm");
+const type_graphql_1 = require("type-graphql");
+const shell_1 = require("@things-factory/shell");
+/*
+ * 인제스트 창 하나 — **동기화 추이를 재기동 뒤에도 이어 보기 위한 행.**
+ *
+ * ── 왜 창마다이고 건마다가 아닌가 ───────────────────────────────────────────
+ * 거부마다 행을 쓰면 라이브 계측 규모에서 초당 1만 행이고, 그 부하가 이벤트 루프로 돌아온다. 창마다면
+ * 트윈 1,000개에 하루 14.4만 행(약 14MB)이다. 그래서 **닫힌 창 하나가 영속의 단위**다.
+ *
+ * 건마다 남기는 자리는 이미 따로 있다: 시나리오 경로가 `PayloadLog` 로 dead-letter 를 남긴다(배치성
+ * 유입이라 건수가 감당된다). 이 표는 그것을 대신하지 않고 **추이**를 답한다.
+ *
+ * ── 왜 사유·표본은 여기 없나 ────────────────────────────────────────────────
+ * 사유 문구는 길고 표본에는 **고객의 레코드 원문**이 들어 있다. 그것을 창마다 영속하면 표가 커지고
+ * 고객 데이터가 오래 남는다. 사유와 표본은 메모리 장부가 답하고(최근 6시간), 이 표는 숫자만 든다.
+ *
+ * ── 고치지 않는다 ───────────────────────────────────────────────────────────
+ * 닫힌 창은 지나간 사실이다. 그래서 `updatedAt`·`deletedAt` 을 두지 않는다(저널과 같은 규율).
+ */
+let TwinIngestWindow = class TwinIngestWindow {
+};
+exports.TwinIngestWindow = TwinIngestWindow;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, type_graphql_1.Field)(type => type_graphql_1.ID, { description: 'Unique identifier of the window record.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinIngestWindow.prototype, "id", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => shell_1.Domain),
+    (0, type_graphql_1.Field)(type => shell_1.Domain, { nullable: true, description: 'Owning tenant domain.' }),
+    tslib_1.__metadata("design:type", shell_1.Domain)
+], TwinIngestWindow.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.domain),
+    tslib_1.__metadata("design:type", String)
+], TwinIngestWindow.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Twin runtime instance this window belongs to.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinIngestWindow.prototype, "instanceId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'When the window opened.' }),
+    tslib_1.__metadata("design:type", Date)
+], TwinIngestWindow.prototype, "openedAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'When the window closed. Windows close on the next ingest after the window length elapses, so a feed that stops leaves its last window open and unwritten.' }),
+    tslib_1.__metadata("design:type", Date)
+], TwinIngestWindow.prototype, "closedAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int' }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { description: 'Records offered in this window, whether or not they were accepted.' }),
+    tslib_1.__metadata("design:type", Number)
+], TwinIngestWindow.prototype, "offered", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int' }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { description: 'Records the kernel refused in this window because they did not map — the fix is in the mapping.' }),
+    tslib_1.__metadata("design:type", Number)
+], TwinIngestWindow.prototype, "rejected", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', default: 0 }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, {
+        description: 'Records that mapped fine but never reached the twin, because the twin was not running live while the feed kept delivering. Distinct from rejected: the fix here is to start the twin or disconnect the feed, not to change the mapping. Offered minus rejected minus undelivered is what actually reached the twin.'
+    }),
+    tslib_1.__metadata("design:type", Number)
+], TwinIngestWindow.prototype, "undelivered", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'float', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Float, {
+        nullable: true,
+        description: 'Share of offered records that reached the twin (0–1), rounded to four places. Null when nothing was offered in this window — an empty window is not a perfect one, and writing 1 there would read as "everything passed".'
+    }),
+    tslib_1.__metadata("design:type", Number)
+], TwinIngestWindow.prototype, "acceptedRatio", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', default: 0 }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, {
+        description: 'Journal rows written for this twin during this window. This is a different axis from ingest: a twin driven by a simulator source receives nothing (offered = 0) yet writes what it produces, so without this column its activity appears in no trend at all.'
+    }),
+    tslib_1.__metadata("design:type", Number)
+], TwinIngestWindow.prototype, "journaledRows", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', default: 0 }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, {
+        description: 'Number of journal write round-trips (flushes) behind those rows. Counted separately from the rows themselves so that a regression back to per-delta writes — the defect fixed on 2026-08-20, where each kernel delta cost one insert — is visible as rows-per-flush falling back towards 1.'
+    }),
+    tslib_1.__metadata("design:type", Number)
+], TwinIngestWindow.prototype, "journalFlushes", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'When this record was written.' }),
+    tslib_1.__metadata("design:type", Date)
+], TwinIngestWindow.prototype, "createdAt", void 0);
+exports.TwinIngestWindow = TwinIngestWindow = tslib_1.__decorate([
+    (0, typeorm_1.Entity)(),
+    (0, typeorm_1.Index)('ix_twin_ingest_window_0', (e) => [e.domain, e.instanceId, e.closedAt], { unique: false }),
+    (0, type_graphql_1.ObjectType)({
+        description: 'One closed ingest window for a twin: how many records were offered, accepted and rejected between two times. Written when a window closes (about every 10 minutes per twin) so the sync trend survives a restart and reaches further back than the in-memory ledger. Reasons and rejected-record samples are deliberately not stored here — they live in the in-memory ledger, which covers roughly the last 6 hours.'
+    })
+], TwinIngestWindow);
+//# sourceMappingURL=twin-ingest-window.js.map

package/dist-server/service/twin-ingest-window/twin-ingest-window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-ingest-window.js","sourceRoot":"","sources":["../../../server/service/twin-ingest-window/twin-ingest-window.ts"],"names":[],"mappings":"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","sourcesContent":["import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'\nimport { ObjectType, Field, ID, Int, Float } from 'type-graphql'\n\nimport { Domain } from '@things-factory/shell'\n\n/*\n * 인제스트 창 하나 — **동기화 추이를 재기동 뒤에도 이어 보기 위한 행.**\n *\n * ── 왜 창마다이고 건마다가 아닌가 ───────────────────────────────────────────\n * 거부마다 행을 쓰면 라이브 계측 규모에서 초당 1만 행이고, 그 부하가 이벤트 루프로 돌아온다. 창마다면\n * 트윈 1,000개에 하루 14.4만 행(약 14MB)이다. 그래서 **닫힌 창 하나가 영속의 단위**다.\n *\n * 건마다 남기는 자리는 이미 따로 있다: 시나리오 경로가 `PayloadLog` 로 dead-letter 를 남긴다(배치성\n * 유입이라 건수가 감당된다). 이 표는 그것을 대신하지 않고 **추이**를 답한다.\n *\n * ── 왜 사유·표본은 여기 없나 ────────────────────────────────────────────────\n * 사유 문구는 길고 표본에는 **고객의 레코드 원문**이 들어 있다. 그것을 창마다 영속하면 표가 커지고\n * 고객 데이터가 오래 남는다. 사유와 표본은 메모리 장부가 답하고(최근 6시간), 이 표는 숫자만 든다.\n *\n * ── 고치지 않는다 ───────────────────────────────────────────────────────────\n * 닫힌 창은 지나간 사실이다. 그래서 `updatedAt`·`deletedAt` 을 두지 않는다(저널과 같은 규율).\n */\n@Entity()\n@Index('ix_twin_ingest_window_0', (e: TwinIngestWindow) => [e.domain, e.instanceId, e.closedAt], { unique: false })\n@ObjectType({\n  description:\n    'One closed ingest window for a twin: how many records were offered, accepted and rejected between two times. Written when a window closes (about every 10 minutes per twin) so the sync trend survives a restart and reaches further back than the in-memory ledger. Reasons and rejected-record samples are deliberately not stored here — they live in the in-memory ledger, which covers roughly the last 6 hours.'\n})\nexport class TwinIngestWindow {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID, { description: 'Unique identifier of the window record.' })\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })\n  domain?: Domain\n\n  @RelationId((e: TwinIngestWindow) => e.domain)\n  domainId?: string\n\n  @Column()\n  @Field({ description: 'Twin runtime instance this window belongs to.' })\n  instanceId: string\n\n  @Column()\n  @Field({ description: 'When the window opened.' })\n  openedAt: Date\n\n  @Column()\n  @Field({ description: 'When the window closed. Windows close on the next ingest after the window length elapses, so a feed that stops leaves its last window open and unwritten.' })\n  closedAt: Date\n\n  @Column({ type: 'int' })\n  @Field(type => Int, { description: 'Records offered in this window, whether or not they were accepted.' })\n  offered: number\n\n  @Column({ type: 'int' })\n  @Field(type => Int, { description: 'Records the kernel refused in this window because they did not map — the fix is in the mapping.' })\n  rejected: number\n\n  /*\n   * 거부와 따로 센다 — **처방이 다르다.**\n   *\n   * 트윈이 라이브로 돌지 않으면 커널이 레코드를 버린다. 그것을 거부에 합치면 「매핑을 고쳐라」로 읽히고,\n   * 통과에 합치면 멈춘 트윈이 100% 로 보인다(실제로 그렇게 떴다). 그래서 제3의 수로 남긴다.\n   */\n  @Column({ type: 'int', default: 0 })\n  @Field(type => Int, {\n    description:\n      'Records that mapped fine but never reached the twin, because the twin was not running live while the feed kept delivering. Distinct from rejected: the fix here is to start the twin or disconnect the feed, not to change the mapping. Offered minus rejected minus undelivered is what actually reached the twin.'\n  })\n  undelivered: number\n\n  /*\n   * 통과율을 **함께 적는다.** 읽는 쪽에서 나누게 하면 소비처마다 반올림이 갈리고(0.999 를 1 로 쓰는\n   * 곳이 생긴다), 제시가 0 인 창에서 0으로 나누는 실수가 각자 생긴다. 제시가 0 이면 **비어 둔다** —\n   * 1 로 채우면 「전부 통과」로 읽힌다.\n   */\n  @Column({ type: 'float', nullable: true })\n  @Field(type => Float, {\n    nullable: true,\n    description:\n      'Share of offered records that reached the twin (0–1), rounded to four places. Null when nothing was offered in this window — an empty window is not a perfect one, and writing 1 there would read as \"everything passed\".'\n  })\n  acceptedRatio?: number\n\n  /*\n   * ── 적힌 것도 같은 창에 든다 ────────────────────────────────────────────────\n   * 유입과 **다른 축**이다. 시뮬 트윈은 받는 것 없이 자기가 낸 사실을 적으므로 `offered` 가 0 이고\n   * `journaledRows` 는 0 이 아니다. 이 칸이 없으면 도는 트윈 대부분이 시뮬인 서버의 활동이 어느 추이에도\n   * 남지 않는다(계기는 지금만 답하고 재기동에 0 으로 돌아간다).\n   *\n   * 두 수를 따로 세는 이유: 2026-08-20 에 고친 것이 **행당 왕복**이다(델타마다 한 번 → 창당 한 번).\n   * 행만 세면 그 개선도, 되돌아가는 것도 보이지 않는다.\n   */\n  @Column({ type: 'int', default: 0 })\n  @Field(type => Int, {\n    description:\n      'Journal rows written for this twin during this window. This is a different axis from ingest: a twin driven by a simulator source receives nothing (offered = 0) yet writes what it produces, so without this column its activity appears in no trend at all.'\n  })\n  journaledRows: number\n\n  @Column({ type: 'int', default: 0 })\n  @Field(type => Int, {\n    description:\n      'Number of journal write round-trips (flushes) behind those rows. Counted separately from the rows themselves so that a regression back to per-delta writes — the defect fixed on 2026-08-20, where each kernel delta cost one insert — is visible as rows-per-flush falling back towards 1.'\n  })\n  journalFlushes: number\n\n  @CreateDateColumn()\n  @Field({ nullable: true, description: 'When this record was written.' })\n  createdAt?: Date\n}\n"]}

package/dist-server/service/twin-instance/twin-instance.js.map

@@ -1 +1 @@
-{"version":3,"file":"twin-instance.js","sourceRoot":"","sources":["../../../server/service/twin-instance/twin-instance.ts"],"names":[],"mappings":"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","sourcesContent":["import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'\nimport { ObjectType, Field, ID } from 'type-graphql'\n\nimport { Domain, ScalarObject } from '@things-factory/shell'\nimport { User } from '@things-factory/auth-base'\nimport { modelColumnTransformer } from '../../engine/model-vocabulary.js'\n\n/*\n * TwinInstance — 트윈 인스턴스 레지스트리(재부팅 복구의 앵커).\n * 복구(DB→replay)는 model(마스터 청사진)가 있어야 이벤트를 상태로 다시 계산할 수 있다 → model·kind 를 영속.\n * 이벤트(TwinEvent)와 달리 가변(status 갱신) — 인스턴스의 \"현재 등록 상태\".\n * model 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).\n * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)\n */\n@Entity()\n@Index('ix_twin_instance_0', (e: TwinInstance) => [e.domain, e.instanceId], { unique: true })\n@Index('ix_twin_instance_1', (e: TwinInstance) => [e.domain, e.spaceId]) // 공간→인스턴스 1급 질의(공간 중심 존재론)\n@ObjectType({ description: 'Registry of a hosted twin runtime instance — anchors reboot recovery (model + kind).' })\nexport class TwinInstance {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID, { description: 'Unique identifier of the registry record.' })\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })\n  domain?: Domain\n\n  @RelationId((e: TwinInstance) => e.domain)\n  domainId?: string\n\n  @Column()\n  @Field({ description: 'Twin runtime instance id (unique within a domain).' })\n  instanceId: string\n\n  /**\n   * **사람이 부르는 이름** — 업무키(`instanceId`)와 나란히 두는 표시명(프레임워크 엔티티 규약).\n   *\n   * ── 왜 업무키와 이름을 나눠 두나 ─────────────────────────────────────────────\n   * `instanceId` 는 URL·저널·구독이 전부 쓰는 **계약**이라 바꿀 수 없다. 반대로 이름은 바뀌고,\n   * 중복되고(사이트 둘에 \"도장\" 이 있는 것이 정상), 언어마다 다르다. 둘을 한 컬럼에 담으면 개명이\n   * 곧 다른 트윈이 되고 재동기가 끊긴다 — 그래서 나눈다(이 저장소에서 식별자가 밖에서 오는 것은\n   * 전부 이 규약을 쓴다: `spaceId`·`locationId`·`equipmentId`·`operationKey`).\n   *\n   * 나눴으면 **이름을 반드시 함께 둬야 한다.** 이 자리가 없던 동안 사이트 이름은 model 안에만 있어서\n   * 목록이 `crew-two` 만 보였다 — 나누기만 하고 절반을 빼먹으면 화면에는 id 만 남는다.\n   *\n   * 원본이 이름을 말하지 않으면 비운다(id 를 베끼지 않는다).\n   */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Human name of this twin (the site name from its master). Empty when the source does not name it — never copied from instanceId.' })\n  name?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Longer description when the source provides one.' })\n  description?: string\n\n  /* 어느 도메인 커널이 이 트윈을 운영하는가. 커널 없는 트윈은 없으므로 비어 있을 수 없다\n     (`TwinEngine.start`·`register` 모두 필수 인자로 받는다). */\n  @Column()\n  @Field({ description: 'Domain kernel kind: wms | yms | mes.' })\n  kind: string\n\n  /*\n   * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나(ADR-0029 §2).\n   *\n   *   'resync' = 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다 → startLive).\n   *   'resume' = 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).\n   *   'reset'  = 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험 — 백지 시작이 선언된 거동이다).\n   *\n   * ── 왜 트윈에 남았나 (옛 이름 `realityMode`) ────────────────────────────────\n   * 「현실이 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) —\n   * 트윈은 한 종류이고 언제나 원본을 반영한다. 그런데 코드가 이 축으로 실제로 가른 것은 **재기동 거동\n   * 하나**였고, 그것은 원본의 성질이 아니라 **트윈과 자기 과거의 관계**다: 같은 시뮬레이터 원본을 보는 두\n   * 트윈이 하나는 이어가고 하나는 매번 처음부터 재현할 수 있다. 그래서 축은 남고 이름만 바뀌었다.\n   *\n   * **비어 있을 수 없고, 기본값도 없다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로\n   * 떨어졌다 — 값이 하나 어긋나는 순간 이력을 지우는 길이다. 이제 읽는 쪽이 **던진다**\n   * (`engine/restart-policy.ts`). 선언은 프로비저닝하는 쪽의 몫이다.\n   */\n  @Column()\n  @Field({ description: \"Restart policy: 'resync' (read again from the external source) | 'resume' (continue this twin's own journal) | 'reset' (wipe and replay from the seed). No default — an unspecified policy is refused.\" })\n  restartPolicy: string\n\n  /* 읽을 때 어휘 세대를 흡수한다(`nodes`/`movers`/`equipmentList` → `locations`/`equipment`).  (vocabulary-guard: allow — 세대 이름 없이는 설명할 수 없다.)\n     자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠지고, 빠진 것은 오류가 아니라 **빈 공장**이라\n     조용하다(2026-08-06: 모델러 엔티티 목록이 통째로 비었다). 상세 `engine/model-vocabulary.ts`. */\n  @Column({ type: 'simple-json', nullable: true, transformer: modelColumnTransformer })\n  @Field(type => ScalarObject, { nullable: true, description: 'TwinModelDef blueprint (locations/equipment) required to replay events into state. Older stored boards used nodes/movers/equipmentList; they are normalised on read so consumers see one vocabulary.' }) // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)\n  model?: any\n\n  /*\n   * 로컬 선언 겹 — **구조는 원천이, 수는 우리가.**\n   *\n   * 요금 단가·계약 정보·축전지 충전율처럼 원 시스템이 모르는 값을 넣는 자리다. `model` 에 직접 쓰지\n   * 않는 이유는 그것이 **원천의 사본**이기 때문이다: 다시 읽기가 사본을 새로 그리면 직접 쓴 값은 조용히\n   * 사라진다(요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다).\n   *\n   * 그래서 여기 남기고, 모델을 그릴 때마다 그 위에 얹는다(`engine/local-declarations`). 얹힌 값에는\n   * `source: 'local'` 이 붙는다 — 커널 계약의 `PropertySource` 축(`reference` ↔ `local`)이고, 「밖에서\n   * 참조해 온 값이냐, 이 안에서 정한 값이냐」에 답한다.\n   *\n   * **이름에 장소 낱말을 쓰지 않는다**(옛 이름 `siteDeclarations`): 이 코드에서 `site` 는 **외부\n   * 시스템이 부르는 사업장**이고(SAP `P3`·Oracle `W01` 이 같은 현장), 여기 담기는 것은 그 외부 시스템이\n   * **모르는** 값이다 — 이름이 내용과 정반대였다. `space` 도 아니다: 그것은 「어디」에 답하고 이 축은\n   * 「누가 말했나」에 답한다.\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, { nullable: true, description: \"Locally-declared values layered on top of the reference-derived model (tariff, contract, state of charge) — values whose authority sits here, not in the source system. Kept apart from `model` so a resync cannot silently drop them.\" })\n  localDeclarations?: any\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Owning space id (co-location anchor). Promoted from model.spaceId — first-class \"space → its twins\" query (space-centered ontology).' })\n  spaceId?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Owning area id within the space (optional scope). Promoted from model.areaId.' })\n  areaId?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Lifecycle status: running | stopped.' })\n  status?: string\n\n  /*\n   * purpose — 이 인스턴스가 운영 트윈인지, 격리된 벤치 사본인지 1급 선언(이름 접두사가 아니라 속성으로 구별).\n   * 'bench' 는 규모/부하 실험용 격리 사본 — 목록·정리·안전 가드가 이 속성을 키로 동작(운영 트윈 무오염 보장).\n   *\n   * **비어 있을 수 없다.** 프로비저닝이 `register` 에서 'operational' 로 각인하고, 벤치 사본만\n   * `setPurpose` 로 뒤집는다. 예전에는 비워 둔 채 읽는 쪽에서 메웠는데, 그러면 \"운영이라고 선언된 것\"\n   * 과 \"아무도 말하지 않은 것\" 이 같은 값으로 보여서 벤치 격리가 추측에 기대게 된다.\n   */\n  @Column()\n  @Field({ description: \"Instance purpose: 'operational' (real twin) | 'bench' (isolated copy for scale/load experiments).\" })\n  purpose: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'For a bench copy: the source spaceId it was copied from (provenance).' })\n  copyOf?: string\n\n  /**\n   * **이 트윈을 다시 읽는 방법** — 어떤 원본에서 나왔나(`MasterOrigin`).\n   *\n   * 트윈은 원본을 비출 뿐이므로(ADR-0028) 원본이 달라지면 다시 읽어야 한다. 그런데 이 자리가 없던\n   * 동안 트윈은 **자기가 무엇에서 나왔는지 몰랐다** — 어댑터로 들어온 트윈은 `TwinReference` 행이\n   * 있었지만 템플릿으로 세운 트윈에는 아무 표식도 없었고, 그래서 첫날의 모습에 영원히 머무는\n   * 트윈이 만들어졌다. 원천이 무엇이든 여기 한 자리에 남긴다.\n   *\n   * **비어 있을 수 있다** — 이 자리가 생기기 전에 만들어진 트윈이 그렇다. 그때는 \"다시 읽을 수\n   * 없다\" 가 사실이므로 화면이 그대로 말한다(짐작해 채우지 않는다).\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, {\n    nullable: true,\n    description:\n      \"How this twin's master can be produced again — {kind:'reference', source} or {kind:'template', templateId, params}. Absent means this twin cannot be re-read from its source.\"\n  })\n  origin?: any\n\n  /*\n   * `revision` 컬럼은 **없앴다**(2026-08-08).\n   *\n   * `ADR-0015` 가 \"정의만 있고 write 안 됨 — 프로비저닝에서 최신 저널 revision 을 반영하도록\n   * 채운다\" 고 적어 두었는데, 채우지 않는 편이 맞다. 저널의 최신 번호는 **저널이 아는 사실**이고\n   * (`TwinEngine.list` 가 `MAX(revision)` 으로 낸다), 여기 복제하면 **같은 사실의 집이 둘**이 된다.\n   * 이 세션에만 그 부류를 셋 겪었다(`model.operations` 두 집 · `materials` 두 집 · tenantId 중복).\n   *\n   * 복제한 값은 반드시 어긋난다 — 저널은 틱마다 늘고 이 컬럼은 저장할 때만 갱신되므로, 화면이\n   * 어느 쪽을 읽느냐로 다른 숫자가 나온다. 그 조용한 어긋남을 만들 이유가 없다.\n   */\n\n  @CreateDateColumn()\n  @Field({ nullable: true, description: 'Timestamp when the instance was first registered.' })\n  createdAt?: Date\n\n  @UpdateDateColumn()\n  @Field({ nullable: true, description: 'Timestamp when the instance registry row was last updated.' })\n  updatedAt?: Date\n\n  /*\n   * 누가 만들고 누가 고쳤나 — **이 행은 사람이 만든다**(프로비저닝은 사용자 행위)이므로 규약의\n   * 풀세트를 갖는다. 투영 행(자리·설비·공정)은 반대로 인제스트가 그린 것이라 저자가 사람이 아니고,\n   * 그 저자는 `sourceRef`+`ingestedAt` 이 이미 말한다 — 그래서 그쪽에는 두지 않는다.\n   *\n   * 비어 있을 수 있다: 부팅 자동 프로비저닝처럼 **사람이 없는 경로**로 만들어진 행이 그렇다.\n   * 그때 아무 사용자를 적어 넣으면 감사 기록이 거짓이 된다.\n   */\n  @ManyToOne(type => User, { nullable: true })\n  @Field(type => User, { nullable: true, description: 'The user who first provisioned this twin. Empty when it was created by a system path (boot provisioning).' })\n  creator?: User\n\n  @RelationId((e: TwinInstance) => e.creator)\n  creatorId?: string\n\n  @ManyToOne(type => User, { nullable: true })\n  @Field(type => User, { nullable: true, description: 'The user who last changed this twin registry row.' })\n  updater?: User\n\n  @RelationId((e: TwinInstance) => e.updater)\n  updaterId?: string\n}\n"]}
+{"version":3,"file":"twin-instance.js","sourceRoot":"","sources":["../../../server/service/twin-instance/twin-instance.ts"],"names":[],"mappings":"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","sourcesContent":["import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'\nimport { ObjectType, Field, ID } from 'type-graphql'\n\nimport { Domain, ScalarObject } from '@things-factory/shell'\nimport { User } from '@things-factory/auth-base'\nimport { modelColumnTransformer } from '../../engine/model-vocabulary.js'\n\n/*\n * TwinInstance — 트윈 인스턴스 레지스트리(재부팅 복구의 앵커).\n * 복구(DB→replay)는 model(마스터 청사진)가 있어야 이벤트를 상태로 다시 계산할 수 있다 → model·kind 를 영속.\n * 이벤트(TwinEvent)와 달리 가변(status 갱신) — 인스턴스의 \"현재 등록 상태\".\n * model 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).\n * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)\n */\n@Entity()\n@Index('ix_twin_instance_0', (e: TwinInstance) => [e.domain, e.instanceId], { unique: true })\n@Index('ix_twin_instance_1', (e: TwinInstance) => [e.domain, e.spaceId]) // 공간→인스턴스 1급 질의(공간 중심 존재론)\n@ObjectType({ description: 'Registry of a hosted twin runtime instance — anchors reboot recovery (model + kind).' })\nexport class TwinInstance {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID, { description: 'Unique identifier of the registry record.' })\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })\n  domain?: Domain\n\n  @RelationId((e: TwinInstance) => e.domain)\n  domainId?: string\n\n  @Column()\n  @Field({ description: 'Twin runtime instance id (unique within a domain).' })\n  instanceId: string\n\n  /**\n   * **사람이 부르는 이름** — 업무키(`instanceId`)와 나란히 두는 표시명(프레임워크 엔티티 규약).\n   *\n   * ── 왜 업무키와 이름을 나눠 두나 ─────────────────────────────────────────────\n   * `instanceId` 는 URL·저널·구독이 전부 쓰는 **계약**이라 바꿀 수 없다. 반대로 이름은 바뀌고,\n   * 중복되고(사이트 둘에 \"도장\" 이 있는 것이 정상), 언어마다 다르다. 둘을 한 컬럼에 담으면 개명이\n   * 곧 다른 트윈이 되고 재동기가 끊긴다 — 그래서 나눈다(이 저장소에서 식별자가 밖에서 오는 것은\n   * 전부 이 규약을 쓴다: `spaceId`·`locationId`·`equipmentId`·`operationKey`).\n   *\n   * 나눴으면 **이름을 반드시 함께 둬야 한다.** 이 자리가 없던 동안 사이트 이름은 model 안에만 있어서\n   * 목록이 `crew-two` 만 보였다 — 나누기만 하고 절반을 빼먹으면 화면에는 id 만 남는다.\n   *\n   * 원본이 이름을 말하지 않으면 비운다(id 를 베끼지 않는다).\n   */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Human name of this twin (the site name from its master). Empty when the source does not name it — never copied from instanceId.' })\n  name?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Longer description when the source provides one.' })\n  description?: string\n\n  /* 어느 도메인 커널이 이 트윈을 운영하는가. 커널 없는 트윈은 없으므로 비어 있을 수 없다\n     (`TwinEngine.start`·`register` 모두 필수 인자로 받는다). */\n  @Column()\n  @Field({ description: 'Domain kernel kind: wms | yms | mes.' })\n  kind: string\n\n  /*\n   * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나(ADR-0029 §2).\n   *\n   *   'resync' = 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다 → startLive).\n   *   'resume' = 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).\n   *   'reset'  = 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험 — 백지 시작이 선언된 거동이다).\n   *\n   * ── 왜 트윈에 남았나 (옛 이름 `realityMode`) ────────────────────────────────\n   * 「현실이 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) —\n   * 트윈은 한 종류이고 언제나 원본을 반영한다. 그런데 코드가 이 축으로 실제로 가른 것은 **재기동 거동\n   * 하나**였고, 그것은 원본의 성질이 아니라 **트윈과 자기 과거의 관계**다: 같은 시뮬레이터 원본을 보는 두\n   * 트윈이 하나는 이어가고 하나는 매번 처음부터 재현할 수 있다. 그래서 축은 남고 이름만 바뀌었다.\n   *\n   * **비어 있을 수 없고, 기본값도 없다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로\n   * 떨어졌다 — 값이 하나 어긋나는 순간 이력을 지우는 길이다. 이제 읽는 쪽이 **오류를 낸다**\n   * (`engine/restart-policy.ts`). 선언은 프로비저닝하는 쪽의 몫이다.\n   */\n  @Column()\n  @Field({ description: \"Restart policy: 'resync' (read again from the external source) | 'resume' (continue this twin's own journal) | 'reset' (wipe and replay from the seed). No default — an unspecified policy is refused.\" })\n  restartPolicy: string\n\n  /* 읽을 때 어휘 세대를 흡수한다(`nodes`/`movers`/`equipmentList` → `locations`/`equipment`).  (vocabulary-guard: allow — 세대 이름 없이는 설명할 수 없다.)\n     자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠지고, 빠진 것은 오류가 아니라 **빈 공장**이라\n     조용하다(2026-08-06: 모델러 엔티티 목록이 통째로 비었다). 상세 `engine/model-vocabulary.ts`. */\n  @Column({ type: 'simple-json', nullable: true, transformer: modelColumnTransformer })\n  @Field(type => ScalarObject, { nullable: true, description: 'TwinModelDef blueprint (locations/equipment) required to replay events into state. Older stored boards used nodes/movers/equipmentList; they are normalised on read so consumers see one vocabulary.' }) // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)\n  model?: any\n\n  /*\n   * 로컬 선언 겹 — **구조는 원천이, 수는 우리가.**\n   *\n   * 요금 단가·계약 정보·축전지 충전율처럼 원 시스템이 모르는 값을 넣는 자리다. `model` 에 직접 쓰지\n   * 않는 이유는 그것이 **원천의 사본**이기 때문이다: 다시 읽기가 사본을 새로 그리면 직접 쓴 값은 조용히\n   * 사라진다(요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다).\n   *\n   * 그래서 여기 남기고, 모델을 그릴 때마다 그 위에 얹는다(`engine/local-declarations`). 얹힌 값에는\n   * `source: 'local'` 이 붙는다 — 커널 계약의 `PropertySource` 축(`reference` ↔ `local`)이고, 「밖에서\n   * 참조해 온 값이냐, 이 안에서 정한 값이냐」에 답한다.\n   *\n   * **이름에 장소 낱말을 쓰지 않는다**(옛 이름 `siteDeclarations`): 이 코드에서 `site` 는 **외부\n   * 시스템이 부르는 사업장**이고(SAP `P3`·Oracle `W01` 이 같은 현장), 여기 담기는 것은 그 외부 시스템이\n   * **모르는** 값이다 — 이름이 내용과 정반대였다. `space` 도 아니다: 그것은 「어디」에 답하고 이 축은\n   * 「누가 말했나」에 답한다.\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, { nullable: true, description: \"Locally-declared values layered on top of the reference-derived model (tariff, contract, state of charge) — values whose authority sits here, not in the source system. Kept apart from `model` so a resync cannot silently drop them.\" })\n  localDeclarations?: any\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Owning space id (co-location anchor). Promoted from model.spaceId — first-class \"space → its twins\" query (space-centered ontology).' })\n  spaceId?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Owning area id within the space (optional scope). Promoted from model.areaId.' })\n  areaId?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Lifecycle status: running | stopped.' })\n  status?: string\n\n  /*\n   * purpose — 이 인스턴스가 운영 트윈인지, 격리된 벤치 사본인지 1급 선언(이름 접두사가 아니라 속성으로 구별).\n   * 'bench' 는 규모/부하 실험용 격리 사본 — 목록·정리·안전 가드가 이 속성을 키로 동작(운영 트윈 무오염 보장).\n   *\n   * **비어 있을 수 없다.** 프로비저닝이 `register` 에서 'operational' 로 각인하고, 벤치 사본만\n   * `setPurpose` 로 뒤집는다. 예전에는 비워 둔 채 읽는 쪽에서 메웠는데, 그러면 \"운영이라고 선언된 것\"\n   * 과 \"아무도 말하지 않은 것\" 이 같은 값으로 보여서 벤치 격리가 추측에 기대게 된다.\n   */\n  @Column()\n  @Field({ description: \"Instance purpose: 'operational' (real twin) | 'bench' (isolated copy for scale/load experiments).\" })\n  purpose: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'For a bench copy: the source spaceId it was copied from (provenance).' })\n  copyOf?: string\n\n  /**\n   * **이 트윈을 다시 읽는 방법** — 어떤 원본에서 나왔나(`MasterOrigin`).\n   *\n   * 트윈은 원본을 비출 뿐이므로(ADR-0028) 원본이 달라지면 다시 읽어야 한다. 그런데 이 자리가 없던\n   * 동안 트윈은 **자기가 무엇에서 나왔는지 몰랐다** — 어댑터로 들어온 트윈은 `TwinReference` 행이\n   * 있었지만 템플릿으로 세운 트윈에는 아무 표식도 없었고, 그래서 첫날의 모습에 영원히 머무는\n   * 트윈이 만들어졌다. 원천이 무엇이든 여기 한 자리에 남긴다.\n   *\n   * **비어 있을 수 있다** — 이 자리가 생기기 전에 만들어진 트윈이 그렇다. 그때는 \"다시 읽을 수\n   * 없다\" 가 사실이므로 화면이 그대로 말한다(짐작해 채우지 않는다).\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, {\n    nullable: true,\n    description:\n      \"How this twin's master can be produced again — {kind:'reference', source} or {kind:'template', templateId, params}. Absent means this twin cannot be re-read from its source.\"\n  })\n  origin?: any\n\n  /*\n   * `revision` 컬럼은 **없앴다**(2026-08-08).\n   *\n   * `ADR-0015` 가 \"정의만 있고 write 안 됨 — 프로비저닝에서 최신 저널 revision 을 반영하도록\n   * 채운다\" 고 적어 두었는데, 채우지 않는 편이 맞다. 저널의 최신 번호는 **저널이 아는 사실**이고\n   * (`TwinEngine.list` 가 `MAX(revision)` 으로 낸다), 여기 복제하면 **같은 사실의 집이 둘**이 된다.\n   * 이 세션에만 그 부류를 셋 겪었다(`model.operations` 두 집 · `materials` 두 집 · tenantId 중복).\n   *\n   * 복제한 값은 반드시 어긋난다 — 저널은 틱마다 늘고 이 컬럼은 저장할 때만 갱신되므로, 화면이\n   * 어느 쪽을 읽느냐로 다른 숫자가 나온다. 그 조용한 어긋남을 만들 이유가 없다.\n   */\n\n  @CreateDateColumn()\n  @Field({ nullable: true, description: 'Timestamp when the instance was first registered.' })\n  createdAt?: Date\n\n  @UpdateDateColumn()\n  @Field({ nullable: true, description: 'Timestamp when the instance registry row was last updated.' })\n  updatedAt?: Date\n\n  /*\n   * 누가 만들고 누가 고쳤나 — **이 행은 사람이 만든다**(프로비저닝은 사용자 행위)이므로 규약의\n   * 풀세트를 갖는다. 투영 행(자리·설비·공정)은 반대로 인제스트가 그린 것이라 저자가 사람이 아니고,\n   * 그 저자는 `sourceRef`+`ingestedAt` 이 이미 말한다 — 그래서 그쪽에는 두지 않는다.\n   *\n   * 비어 있을 수 있다: 부팅 자동 프로비저닝처럼 **사람이 없는 경로**로 만들어진 행이 그렇다.\n   * 그때 아무 사용자를 적어 넣으면 감사 기록이 거짓이 된다.\n   */\n  @ManyToOne(type => User, { nullable: true })\n  @Field(type => User, { nullable: true, description: 'The user who first provisioned this twin. Empty when it was created by a system path (boot provisioning).' })\n  creator?: User\n\n  @RelationId((e: TwinInstance) => e.creator)\n  creatorId?: string\n\n  @ManyToOne(type => User, { nullable: true })\n  @Field(type => User, { nullable: true, description: 'The user who last changed this twin registry row.' })\n  updater?: User\n\n  @RelationId((e: TwinInstance) => e.updater)\n  updaterId?: string\n}\n"]}

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

@@ -2,10 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TwinJournalQuery = void 0;
 const tslib_1 = require("tslib");
+const log_js_1 = require("../../engine/log.js");
 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 journal_count_js_1 = require("../twin-event/journal-count.js");
 const twin_event_type_js_1 = require("../twin-event/twin-event-type.js");
 const index_js_1 = require("../../engine/index.js");
 const state_axes_js_1 = require("../../engine/state-axes.js");
@@ -17,6 +19,11 @@ const kpi_query_js_1 = require("../../engine/kpi-query.js");
  * twinReplay : 내구 저널을 replay 해 상태 재구성(재부팅 복구·시간여행) — untilRevision 으로 임의 과거.
  * (실시간 스트림은 twinState subscription, 명령은 twin-control mutation. 이건 '질의' 표면.)
  */
+/*
+ * 건수 상한은 **저널 세기의 문**에서 온다(`journal-count.ts`) — 값과 규율이 두 곳에 흩어지면 한쪽만
+ * 고쳐진다. 근거(2026-08-22 실측): 상한 1만이면 0.04초, 상한 없이 세면 5.32초(저널 358만 행).
+ */
+const COUNT_CAP = journal_count_js_1.JOURNAL_COUNT_CAP;
 /**
  * 시각 필터 값을 날짜로 — 배열(between)이면 원소마다.
  *
@@ -45,8 +52,31 @@ let TwinJournalQuery = class TwinJournalQuery {
             where.revision = (0, typeorm_1.MoreThanOrEqual)(fromRevision);
         else if (toRevision != null)
             where.revision = (0, typeorm_1.LessThanOrEqual)(toRevision);
-        /* 최신순(DESC) 기본 — Ledger/recent 뷰. 범위 필터로 시간여행 구간 조회도 가능. */
-        return (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).find({ where, order: { revision: 'DESC' }, take: limit ?? 200 });
+        /*
+         * 최신순(DESC) 기본 — Ledger/recent 뷰. 범위 필터로 시간여행 구간 조회도 가능.
+         *
+         * ── 정렬 축을 **거르는 축과 맞춘다** (2026-08-22 실측) ─────────────────────
+         * `untilTime` 경로는 `eventTime <= T` 로 거르면서 `revision` 으로 정렬했다. 그러면 sqlite 는 조건에
+         * 맞는 행을 **전부 찾아 전부 정렬한 뒤** 상한을 적용한다 — 상한이 정렬 뒤에 걸리므로 200건을 얻는
+         * 데도 전량 정렬을 치른다. 실측(인스턴스 하나가 375만 행):
+         *
+         *   ORDER BY revision DESC              → 33.4초
+         *   ORDER BY eventTime DESC, revision DESC → 0.007초   (4,700배)
+         *
+         * 계획이 그것을 그대로 말한다: 앞은 `USE TEMP B-TREE FOR ORDER BY`(전체 정렬), 뒤는
+         * `... FOR LAST TERM OF ORDER BY` — 시각은 인덱스(`ix_twin_event_1`)에서 순서대로 나오고
+         * **동시각만** 임시 정렬한다.
+         *
+         * **리비전 경로는 그대로 둔다.** 그때는 거르는 축이 `revision` 이고 정렬도 `revision` 이라 이미
+         * 맞아 있다(`ix_twin_event_0`). 축이 어긋난 경로만 고친다 — 맞는 자리를 건드리면 그쪽이 어긋난다.
+         *
+         * 순서의 뜻이 **완전히 같지는 않다**(측정해서 고친 문장): `revision` 순서와 `eventTime` 순서가
+         * 어긋나는 자리가 실재한다(426만 행 중 7건 — 미러는 원본의 시각을 싣고 도착 순서로 리비전을 받는다).
+         * 이 목록은 사람이 이력을 훑는 화면이고 **시각순으로 보는 것이 그 화면의 뜻**이므로, 그 어긋남은
+         * 결함이 아니라 오히려 맞는 순서다. 동시각의 순서를 위해 `revision` 을 둘째 축으로 남긴다.
+         */
+        const order = untilTime != null ? { eventTime: 'DESC', revision: 'DESC' } : { revision: 'DESC' };
+        return (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).find({ where, order, take: limit ?? 200 });
     }
     /**
      * 저널 목록 — things-factory 표준 목록 계약(`ListParam` → `{ items, total }`).
@@ -108,11 +138,34 @@ let TwinJournalQuery = class TwinJournalQuery {
         });
         /* 대상 범위는 호출자가 필터로 빼먹을 수 있는 값이 아니다 — 계약상 필수라 여기서 강제한다. */
         qb.andWhere(`${qb.alias}.instanceId IN (:...instanceIds)`, { instanceIds });
-        const [items, total] = await qb.getManyAndCount();
+        /*
+         * ── 건수는 **상한까지만** 센다 (2026-08-22 실측) ──────────────────────────
+         * 예전에는 `getManyAndCount()` 였다. 그 두 번째 질의가 조건에 맞는 행을 **전부** 세는데, 실측한
+         * 개발 저널에서 트윈 하나가 358만 행이라 **한 번에 5.32초**였다. 이력 화면을 열 때마다 그것을
+         * 물었고, 그 5초 동안 이벤트 루프가 다른 요청을 처리하지 못했다.
+         *
+         * 상한을 두면 같은 답이 **0.04초**다(130배). 상한을 넘으면 정확한 수를 모르는 것이 사실이므로
+         * 목록 규약의 「서버 상한에 부딪힘(total 모름)」 갈래로 낸다 — 화면은 「처음 N 건만」이라고 말하고
+         * 좁히기를 권한다. **조용히 자르지 않는다**: 상한을 넘었다는 사실을 `capped` 로 함께 낸다.
+         *
+         * 왜 하위 질의로 세지 않나: 5개 드라이버에서 같이 도는 형태여야 한다(이 저장소의 절대 규칙).
+         * 그래서 **키 컬럼만 상한까지 읽어 세는** 방식을 쓴다 — 색인만 읽으므로 행 본문을 만들지 않는다.
+         */
+        const items = await qb.getMany();
+        const probe = qb
+            .clone()
+            .orderBy() /* 세는 데 순서는 필요 없다 — 정렬을 남기면 임의 축에서 전체 정렬이 된다. */
+            .skip(0)
+            .take(COUNT_CAP + 1)
+            .select(`${qb.alias}.id`);
+        const counted = await probe.getRawMany();
+        const capped = counted.length > COUNT_CAP;
+        /* 상한을 넘었으면 **전체 수를 모른다** — 상한값을 전체로 적으면 화면이 거짓을 말한다. */
+        const total = capped ? undefined : counted.length;
         /* 다음 커서는 **이번 페이지의 마지막 행**에서 만든다. 페이지가 상한보다 짧으면 뒤가 없다. */
         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 };
+        return { items, total, capped, countCap: COUNT_CAP, nextCursor };
     }
     /**
      * 업무 KPI — 시간창 처리량·소요시간·자원 점유. 저널을 **접어서** 만든다(새 계측을 주입하지 않는다).
@@ -155,7 +208,7 @@ let TwinJournalQuery = class TwinJournalQuery {
         const picked = (0, state_axes_js_1.pickAxes)(state, axes);
         /* 오타를 조용히 넘기지 않는다 — 화면이 빈 채로 뜨는 이유를 아무도 모르게 되는 것이 가장 나쁘다. */
         if (picked.unknown.length)
-            console.warn(`[twin] twinReplay: unknown axes ignored for "${instanceId}": ${picked.unknown.join(', ')}`);
+            (0, log_js_1.twinWarn)(`[twin] twinReplay: unknown axes ignored for "${instanceId}": ${picked.unknown.join(', ')}`);
         if (!attentionLimit || !picked.state?.attentions)
             return picked.state;
         const d = (0, attention_digest_js_1.digestAttentions)(picked.state.attentions, attentionLimit);