@things-factory/headless-twin 10.0.14 → 10.0.17

package/dist-server/service/twin-subject/item-resolver.d.ts

@@ -0,0 +1,10 @@
+import type { ItemResolver } from './event-subjects.js';
+/**
+ * 그 트윈의 품목 판정 함수 — 선언이 없으면 `undefined`(그때는 품목 줄을 만들지 않는다).
+ *
+ * 선언을 모르는 트윈에서 품목을 지어내지 않는다. 개체 줄(`lot`)은 그대로 적히므로 이력 조회는 로트로
+ * 답할 수 있고, 품목 축만 비어 있다. 그 사실을 조회하는 쪽이 말한다.
+ */
+export declare function itemResolverFor(domainId: string, instanceId: string, model: any): ItemResolver | undefined;
+/** 시험이 쓰는 초기화 — 프로세스 안의 기억이므로 시험마다 비운다. */
+export declare function resetItemResolverMemo(): void;

package/dist-server/service/twin-subject/item-resolver.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.itemResolverFor = itemResolverFor;
+exports.resetItemResolverMemo = resetItemResolverMemo;
+const item_ref_js_1 = require("../twin-model/item-ref.js");
+/*
+ * **개체 식별자 → 선언된 품목** — 대상별 사건 목록에 품목 줄을 적기 위한 것.
+ *
+ * ── 왜 문자열을 자르지 않나 ─────────────────────────────────────────────────
+ * 저장된 식별자에 품목과 로트가 붙어 있다.
+ *
+ *   https://seunghwa.net/class/product-M0000438-lot-L2403090386
+ *
+ * 여기서 품목을 꺼내려면 `-lot-` 이 로트를 가리킨다는 것을 알아야 하는데, 그 부호는 연결된 시스템마다
+ * 다르고 커널 계약이 정한 적이 없다. 한 시스템의 관습을 규칙으로 굳히면 이 코드가 그 시스템 위에 서게
+ * 된다(`item-ref.ts` 가 같은 판단을 적어 두었다).
+ *
+ * 그래서 **그 트윈의 선언과 견주어** 판정한다. 선언된 품목 중 이 식별자가 가리키는 것을 찾고, 후보가
+ * 둘 이상이면 답하지 않는다 — 짐작으로 이으면 남의 품목 이력에 이 사건이 섞인다.
+ *
+ * ── 왜 기억해 두나 ──────────────────────────────────────────────────────────
+ * 사건마다 부르는 함수다(초당 130건). 같은 개체 식별자가 계속 되풀어 오므로, 한 번 판정한 것은 기억해
+ * 둔다. 트윈의 선언이 바뀌면 그 기억을 버려야 하므로 **선언의 개수와 첫 항목으로 세대**를 만든다 —
+ * 선언이 바뀌면 세대가 달라져 다시 판정한다.
+ */
+/** 트윈마다 기억해 둔 판정 — 세대가 바뀌면 버린다. */
+const memo = new Map();
+/** 한 트윈이 기억할 개체 식별자 수 상한 — 넘으면 비우고 다시 채운다(무한히 자라지 않게). */
+const MEMO_LIMIT = 20_000;
+/**
+ * 선언된 품목의 식별자들을 모은다 — 트윈 모델이 말하는 것만.
+ *
+ * `materialDefinitions` 가 이 트윈이 다루는 품목의 선언이다. 그 항목의 `id` 와, 연결된 시스템의
+ * 어휘로 이어 둔 값(`binding`)을 함께 후보로 둔다 — 개체 식별자는 후자를 앞부분으로 갖는다.
+ */
+function declaredItems(model) {
+    const out = new Map();
+    const defs = model?.productionSpec?.materialDefinitions ?? model?.materialDefinitions;
+    if (!Array.isArray(defs))
+        return out;
+    for (const d of defs) {
+        const id = String(d?.id ?? '').trim();
+        if (!id)
+            continue;
+        out.set(id, id);
+        const binding = d?.binding;
+        const bound = typeof binding === 'string' ? binding : binding?.epcClass ?? binding?.id;
+        const b = String(bound ?? '').trim();
+        if (b)
+            out.set(b, id);
+    }
+    return out;
+}
+/** 선언이 바뀌었는지 값싸게 가리는 표식 — 개수와 첫·끝 항목이면 실제 변경을 잡는다. */
+function generationOf(declared) {
+    const keys = [...declared.keys()];
+    return `${keys.length}:${keys[0] ?? ''}:${keys[keys.length - 1] ?? ''}`;
+}
+/**
+ * 그 트윈의 품목 판정 함수 — 선언이 없으면 `undefined`(그때는 품목 줄을 만들지 않는다).
+ *
+ * 선언을 모르는 트윈에서 품목을 지어내지 않는다. 개체 줄(`lot`)은 그대로 적히므로 이력 조회는 로트로
+ * 답할 수 있고, 품목 축만 비어 있다. 그 사실을 조회하는 쪽이 말한다.
+ */
+function itemResolverFor(domainId, instanceId, model) {
+    const declared = declaredItems(model);
+    if (!declared.size)
+        return undefined;
+    const key = `${domainId}:${instanceId}`;
+    const generation = generationOf(declared);
+    let entry = memo.get(key);
+    if (!entry || entry.generation !== generation) {
+        entry = { generation, declared, seen: new Map() };
+        memo.set(key, entry);
+    }
+    const state = entry;
+    return (epc) => {
+        const hit = state.seen.get(epc);
+        if (hit !== undefined)
+            return hit;
+        /* 판정은 선언이 한다 — 후보가 둘 이상이면 `undefined` 를 내고, 그것을 「모른다」로 기억한다. */
+        const found = (0, item_ref_js_1.resolveByDeclaration)((0, item_ref_js_1.itemRefOf)(epc), state.declared) ?? null;
+        if (state.seen.size >= MEMO_LIMIT)
+            state.seen.clear();
+        state.seen.set(epc, found);
+        return found;
+    };
+}
+/** 시험이 쓰는 초기화 — 프로세스 안의 기억이므로 시험마다 비운다. */
+function resetItemResolverMemo() {
+    memo.clear();
+}
+//# sourceMappingURL=item-resolver.js.map

package/dist-server/service/twin-subject/item-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-resolver.js","sourceRoot":"","sources":["../../../server/service/twin-subject/item-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["import { itemRefOf, resolveByDeclaration } from '../twin-model/item-ref.js'\nimport type { ItemResolver } from './event-subjects.js'\n\n/*\n * **개체 식별자 → 선언된 품목** — 대상별 사건 목록에 품목 줄을 적기 위한 것.\n *\n * ── 왜 문자열을 자르지 않나 ─────────────────────────────────────────────────\n * 저장된 식별자에 품목과 로트가 붙어 있다.\n *\n *   https://seunghwa.net/class/product-M0000438-lot-L2403090386\n *\n * 여기서 품목을 꺼내려면 `-lot-` 이 로트를 가리킨다는 것을 알아야 하는데, 그 부호는 연결된 시스템마다\n * 다르고 커널 계약이 정한 적이 없다. 한 시스템의 관습을 규칙으로 굳히면 이 코드가 그 시스템 위에 서게\n * 된다(`item-ref.ts` 가 같은 판단을 적어 두었다).\n *\n * 그래서 **그 트윈의 선언과 견주어** 판정한다. 선언된 품목 중 이 식별자가 가리키는 것을 찾고, 후보가\n * 둘 이상이면 답하지 않는다 — 짐작으로 이으면 남의 품목 이력에 이 사건이 섞인다.\n *\n * ── 왜 기억해 두나 ──────────────────────────────────────────────────────────\n * 사건마다 부르는 함수다(초당 130건). 같은 개체 식별자가 계속 되풀어 오므로, 한 번 판정한 것은 기억해\n * 둔다. 트윈의 선언이 바뀌면 그 기억을 버려야 하므로 **선언의 개수와 첫 항목으로 세대**를 만든다 —\n * 선언이 바뀌면 세대가 달라져 다시 판정한다.\n */\n\n/** 트윈마다 기억해 둔 판정 — 세대가 바뀌면 버린다. */\nconst memo = new Map<string, { generation: string; declared: Map<string, string>; seen: Map<string, string | null> }>()\n\n/** 한 트윈이 기억할 개체 식별자 수 상한 — 넘으면 비우고 다시 채운다(무한히 자라지 않게). */\nconst MEMO_LIMIT = 20_000\n\n/**\n * 선언된 품목의 식별자들을 모은다 — 트윈 모델이 말하는 것만.\n *\n * `materialDefinitions` 가 이 트윈이 다루는 품목의 선언이다. 그 항목의 `id` 와, 연결된 시스템의\n * 어휘로 이어 둔 값(`binding`)을 함께 후보로 둔다 — 개체 식별자는 후자를 앞부분으로 갖는다.\n */\nfunction declaredItems(model: any): Map<string, string> {\n  const out = new Map<string, string>()\n  const defs = model?.productionSpec?.materialDefinitions ?? model?.materialDefinitions\n  if (!Array.isArray(defs)) return out\n  for (const d of defs) {\n    const id = String(d?.id ?? '').trim()\n    if (!id) continue\n    out.set(id, id)\n    const binding = d?.binding\n    const bound = typeof binding === 'string' ? binding : binding?.epcClass ?? binding?.id\n    const b = String(bound ?? '').trim()\n    if (b) out.set(b, id)\n  }\n  return out\n}\n\n/** 선언이 바뀌었는지 값싸게 가리는 표식 — 개수와 첫·끝 항목이면 실제 변경을 잡는다. */\nfunction generationOf(declared: Map<string, string>): string {\n  const keys = [...declared.keys()]\n  return `${keys.length}:${keys[0] ?? ''}:${keys[keys.length - 1] ?? ''}`\n}\n\n/**\n * 그 트윈의 품목 판정 함수 — 선언이 없으면 `undefined`(그때는 품목 줄을 만들지 않는다).\n *\n * 선언을 모르는 트윈에서 품목을 지어내지 않는다. 개체 줄(`lot`)은 그대로 적히므로 이력 조회는 로트로\n * 답할 수 있고, 품목 축만 비어 있다. 그 사실을 조회하는 쪽이 말한다.\n */\nexport function itemResolverFor(domainId: string, instanceId: string, model: any): ItemResolver | undefined {\n  const declared = declaredItems(model)\n  if (!declared.size) return undefined\n\n  const key = `${domainId}:${instanceId}`\n  const generation = generationOf(declared)\n  let entry = memo.get(key)\n  if (!entry || entry.generation !== generation) {\n    entry = { generation, declared, seen: new Map() }\n    memo.set(key, entry)\n  }\n  const state = entry\n\n  return (epc: string) => {\n    const hit = state.seen.get(epc)\n    if (hit !== undefined) return hit\n    /* 판정은 선언이 한다 — 후보가 둘 이상이면 `undefined` 를 내고, 그것을 「모른다」로 기억한다. */\n    const found = resolveByDeclaration(itemRefOf(epc), state.declared) ?? null\n    if (state.seen.size >= MEMO_LIMIT) state.seen.clear()\n    state.seen.set(epc, found)\n    return found\n  }\n}\n\n/** 시험이 쓰는 초기화 — 프로세스 안의 기억이므로 시험마다 비운다. */\nexport function resetItemResolverMemo(): void {\n  memo.clear()\n}\n"]}

package/dist-server/service/twin-subject/subject-query-shape.d.ts

@@ -0,0 +1,22 @@
+import type { SubjectKind } from './event-subjects.js';
+/** 화면이 저널에 묻던 축 → 파생 테이블의 대상 종류. */
+export declare const AXIS_KIND: Record<string, SubjectKind>;
+export interface SubjectQueryShape {
+    kind: SubjectKind;
+    /** 화면이 건넨 축 값 — 짧게 줄어 있을 수 있다(되돌리는 일은 조회하는 쪽이 한다). */
+    value: string;
+    untilTime?: Date;
+    fromTime?: Date;
+}
+/**
+ * 목록 계약의 조건을 읽어 「대상 하나의 시각순 이력」인지 가린다 — 아니면 `null`.
+ *
+ * 받는 모양
+ *   축 하나(품목·오더·자리·설비)를 `eq` 또는 `search` 로 · 시각 상한이나 구간 · 시각 내림차순 정렬
+ *
+ * 보내는 모양(저널로)
+ *   자유 검색어 · 종류 필터 · 상관 식별자 · 축 둘 이상 · 그 밖의 정렬이나 연산자
+ */
+export declare function readModelShape(params: any, sortings: any[]): SubjectQueryShape | null;
+/** 값을 날짜로 — 못 읽으면 `undefined`(지어내지 않는다). */
+export declare function toDate(v: unknown): Date | undefined;

package/dist-server/service/twin-subject/subject-query-shape.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AXIS_KIND = void 0;
+exports.readModelShape = readModelShape;
+exports.toDate = toDate;
+/*
+ * **이 물음을 파생 테이블로 답할 수 있나** — 순수 판단만 여기 둔다.
+ *
+ * 데이터베이스도 커널도 부르지 않는다. 그래서 시험이 이 파일을 그대로 부를 수 있다(데코레이터가 없다).
+ * 판단이 조회 코드 안에 섞여 있으면 그 판단만 확인할 방법이 없고, 그러면 「어떤 물음이 빠른 경로로
+ * 가는가」가 아무도 읽지 못하는 규칙이 된다.
+ *
+ * 좁게 잡는다. 파생 테이블은 「대상 하나를 시각순으로」에 맞춰 생겼고, 그 모양이 아닌 물음에 억지로
+ * 답하면 목록이 알리지 않고 달라진다. 맞지 않으면 `null` 이고, 부르는 쪽은 저널로 간다.
+ */
+/** 화면이 저널에 묻던 축 → 파생 테이블의 대상 종류. */
+exports.AXIS_KIND = {
+    epc: 'item',
+    orderId: 'order',
+    locationId: 'location',
+    moverId: 'equipment' // vocabulary-guard: allow — 저널의 승격 컬럼 이름(저장된 계약)
+};
+/** 이 경로가 다룰 수 있는 필터 이름 — 이 밖의 필터가 하나라도 있으면 저널로 보낸다. */
+const ALLOWED_FILTERS = new Set(Object.keys(exports.AXIS_KIND).concat('eventTime'));
+/**
+ * 목록 계약의 조건을 읽어 「대상 하나의 시각순 이력」인지 가린다 — 아니면 `null`.
+ *
+ * 받는 모양
+ *   축 하나(품목·오더·자리·설비)를 `eq` 또는 `search` 로 · 시각 상한이나 구간 · 시각 내림차순 정렬
+ *
+ * 보내는 모양(저널로)
+ *   자유 검색어 · 종류 필터 · 상관 식별자 · 축 둘 이상 · 그 밖의 정렬이나 연산자
+ */
+function readModelShape(params, sortings) {
+    const filters = Array.isArray(params?.filters) ? params.filters : [];
+    if (typeof params?.search === 'string' && params.search.trim())
+        return null;
+    for (const f of filters)
+        if (!ALLOWED_FILTERS.has(f?.name))
+            return null;
+    /* 정렬은 시각 내림차순 하나일 때만 — 파생 테이블의 목차가 그 축이다. */
+    if (sortings.length !== 1 || sortings[0]?.name !== 'eventTime' || sortings[0]?.desc !== true)
+        return null;
+    const axisFilters = filters.filter(f => f.name !== 'eventTime');
+    if (axisFilters.length !== 1)
+        return null;
+    const axis = axisFilters[0];
+    const kind = exports.AXIS_KIND[axis.name];
+    if (!kind)
+        return null;
+    /* 축은 값 하나여야 한다 — 여러 값(`in`)이면 목차를 한 번에 타지 못한다. */
+    if (axis.operator !== 'eq' && axis.operator !== 'search')
+        return null;
+    const value = typeof axis.value === 'string' ? axis.value.trim() : '';
+    if (!value)
+        return null;
+    /* 시각은 상한·구간만 받는다(시간여행). 그 밖의 연산자는 뜻이 달라지므로 저널로 보낸다. */
+    let untilTime;
+    let fromTime;
+    for (const f of filters) {
+        if (f.name !== 'eventTime')
+            continue;
+        if (f.operator === 'lte' || f.operator === 'lt') {
+            untilTime = toDate(f.value);
+            if (!untilTime)
+                return null;
+        }
+        else if (f.operator === 'between' && Array.isArray(f.value)) {
+            fromTime = toDate(f.value[0]);
+            untilTime = toDate(f.value[1]);
+            if (!fromTime || !untilTime)
+                return null;
+        }
+        else
+            return null;
+    }
+    return { kind, value, untilTime, fromTime };
+}
+/** 값을 날짜로 — 못 읽으면 `undefined`(지어내지 않는다). */
+function toDate(v) {
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? undefined : v;
+    if (typeof v !== 'string' && typeof v !== 'number')
+        return undefined;
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? undefined : d;
+}
+//# sourceMappingURL=subject-query-shape.js.map

package/dist-server/service/twin-subject/subject-query-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-query-shape.js","sourceRoot":"","sources":["../../../server/service/twin-subject/subject-query-shape.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SubjectKind } from './event-subjects.js'\n\n/*\n * **이 물음을 파생 테이블로 답할 수 있나** — 순수 판단만 여기 둔다.\n *\n * 데이터베이스도 커널도 부르지 않는다. 그래서 시험이 이 파일을 그대로 부를 수 있다(데코레이터가 없다).\n * 판단이 조회 코드 안에 섞여 있으면 그 판단만 확인할 방법이 없고, 그러면 「어떤 물음이 빠른 경로로\n * 가는가」가 아무도 읽지 못하는 규칙이 된다.\n *\n * 좁게 잡는다. 파생 테이블은 「대상 하나를 시각순으로」에 맞춰 생겼고, 그 모양이 아닌 물음에 억지로\n * 답하면 목록이 알리지 않고 달라진다. 맞지 않으면 `null` 이고, 부르는 쪽은 저널로 간다.\n */\n\n/** 화면이 저널에 묻던 축 → 파생 테이블의 대상 종류. */\nexport const AXIS_KIND: Record<string, SubjectKind> = {\n  epc: 'item',\n  orderId: 'order',\n  locationId: 'location',\n  moverId: 'equipment' // vocabulary-guard: allow — 저널의 승격 컬럼 이름(저장된 계약)\n}\n\n/** 이 경로가 다룰 수 있는 필터 이름 — 이 밖의 필터가 하나라도 있으면 저널로 보낸다. */\nconst ALLOWED_FILTERS = new Set(Object.keys(AXIS_KIND).concat('eventTime'))\n\nexport interface SubjectQueryShape {\n  kind: SubjectKind\n  /** 화면이 건넨 축 값 — 짧게 줄어 있을 수 있다(되돌리는 일은 조회하는 쪽이 한다). */\n  value: string\n  untilTime?: Date\n  fromTime?: Date\n}\n\n/**\n * 목록 계약의 조건을 읽어 「대상 하나의 시각순 이력」인지 가린다 — 아니면 `null`.\n *\n * 받는 모양\n *   축 하나(품목·오더·자리·설비)를 `eq` 또는 `search` 로 · 시각 상한이나 구간 · 시각 내림차순 정렬\n *\n * 보내는 모양(저널로)\n *   자유 검색어 · 종류 필터 · 상관 식별자 · 축 둘 이상 · 그 밖의 정렬이나 연산자\n */\nexport function readModelShape(params: any, sortings: any[]): SubjectQueryShape | null {\n  const filters: any[] = Array.isArray(params?.filters) ? params.filters : []\n  if (typeof params?.search === 'string' && params.search.trim()) return null\n  for (const f of filters) if (!ALLOWED_FILTERS.has(f?.name)) return null\n\n  /* 정렬은 시각 내림차순 하나일 때만 — 파생 테이블의 목차가 그 축이다. */\n  if (sortings.length !== 1 || sortings[0]?.name !== 'eventTime' || sortings[0]?.desc !== true) return null\n\n  const axisFilters = filters.filter(f => f.name !== 'eventTime')\n  if (axisFilters.length !== 1) return null\n  const axis = axisFilters[0]\n  const kind = AXIS_KIND[axis.name]\n  if (!kind) return null\n  /* 축은 값 하나여야 한다 — 여러 값(`in`)이면 목차를 한 번에 타지 못한다. */\n  if (axis.operator !== 'eq' && axis.operator !== 'search') return null\n  const value = typeof axis.value === 'string' ? axis.value.trim() : ''\n  if (!value) return null\n\n  /* 시각은 상한·구간만 받는다(시간여행). 그 밖의 연산자는 뜻이 달라지므로 저널로 보낸다. */\n  let untilTime: Date | undefined\n  let fromTime: Date | undefined\n  for (const f of filters) {\n    if (f.name !== 'eventTime') continue\n    if (f.operator === 'lte' || f.operator === 'lt') {\n      untilTime = toDate(f.value)\n      if (!untilTime) return null\n    } else if (f.operator === 'between' && Array.isArray(f.value)) {\n      fromTime = toDate(f.value[0])\n      untilTime = toDate(f.value[1])\n      if (!fromTime || !untilTime) return null\n    } else return null\n  }\n\n  return { kind, value, untilTime, fromTime }\n}\n\n/** 값을 날짜로 — 못 읽으면 `undefined`(지어내지 않는다). */\nexport function toDate(v: unknown): Date | undefined {\n  if (v instanceof Date) return Number.isNaN(v.getTime()) ? undefined : v\n  if (typeof v !== 'string' && typeof v !== 'number') return undefined\n  const d = new Date(v as any)\n  return Number.isNaN(d.getTime()) ? undefined : d\n}\n"]}

package/dist-server/service/twin-subject/twin-subject-backfill.d.ts

@@ -0,0 +1,23 @@
+export interface BackfillResult {
+    instanceId: string;
+    /** 읽은 저널 행 수. */
+    read: number;
+    /** 이 표에 적은 줄 수. */
+    written: number;
+    /** 여기까지 옮겼다(저널 리비전). */
+    upToRevision: number;
+    /** 목표 — 채우기를 시작한 순간의 저널 끝. */
+    targetRevision: number;
+    /** 다 옮겼나. */
+    complete: boolean;
+    /** 예산을 다 써서 멈췄나. */
+    paused: boolean;
+}
+/**
+ * 한 트윈의 저장된 사건을 이 표로 옮긴다 — 예산 안에서.
+ *
+ * 되풀어 부르면 이어서 한다. 넘길 인자가 없다 — 진행 지점을 적어 두기 때문이다.
+ */
+export declare function backfillSubjects(domainId: string, instanceId: string, opts?: {
+    budgetMs?: number;
+}): Promise<BackfillResult>;

package/dist-server/service/twin-subject/twin-subject-backfill.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backfillSubjects = backfillSubjects;
+const shell_1 = require("@things-factory/shell");
+const log_js_1 = require("../../engine/log.js");
+const twin_event_js_1 = require("../twin-event/twin-event.js");
+const twin_instance_js_1 = require("../twin-instance/twin-instance.js");
+const twin_subject_writer_js_1 = require("./twin-subject-writer.js");
+const item_resolver_js_1 = require("./item-resolver.js");
+/*
+ * **이미 저장된 사건을 이 표로 옮긴다** — 요청받은 트윈만.
+ *
+ * ── 왜 기본이 아닌가 ────────────────────────────────────────────────────────
+ * 이 표의 규칙은 「앞으로만 채운다」다. 그래야 새 조회 축이 필요할 때마다 3,128만 줄을 다시 만드는
+ * 구조가 되지 않는다(설계: read-models.md §4).
+ *
+ * 그런데 이미 쌓인 트윈에서 이력을 보려면 그 구간이 있어야 한다. 그래서 **부르면 채우는 도구**로 둔다 —
+ * 마이그레이션이 아니고, 부팅에 자동으로 돌지도 않는다. 트윈을 지정해 부른다.
+ *
+ * ── 어디까지 옮겼는지 적어 둔다 (2026-08-27 · 세 번 틀린 뒤) ─────────────────
+ * 저장하지 않고 표의 내용으로 진행 지점을 알아내려 했고 세 번 틀렸다.
+ *
+ *   ① 표의 최대 리비전 뒤부터    앞으로 채워진 줄의 최댓값이 곧 저널의 끝이라 소급을 다 건너뛴다
+ *   ② 표의 최소 리비전 앞까지    소급이 1부터 적으면 최솟값이 1이 되어 구간이 0으로 접힌다
+ *   ③ 표의 최소 시각 아래로      사건이 시각순으로 오지 않는 트윈에서 곧바로 끝난다
+ *
+ * ③이 결정적이었다. 승화푸드 커넥터는 과거 기록을 되읽으므로 방금 들어온 사건의 시각이 2024년 10월이다.
+ * 그래서 표의 가장 오래된 시각이 이미 저널의 시작과 같아진다.
+ *
+ * 원인은 하나다. **채워진 것은 구간이 아니라 집합이다.** 리비전으로 보든 시각으로 보든 「어디까지」를
+ * 하나의 경계로 말할 수 없다. 그래서 알아내려 하지 않고 **이 프로세스가 든다**(§`inFlight`).
+ *
+ * 리비전 1부터 순서대로 올라간다. 목표는 **채우기를 시작한 순간의 저널 끝**이다 — 그보다 뒤는 앞으로
+ * 채우는 쪽이 이미 적고 있다.
+ *
+ * ── 규율 ────────────────────────────────────────────────────────────────────
+ * **나눠서 옮긴다.** 한 번에 통째로 읽으면 그동안 호스트가 아무 일도 못 한다(sqlite 는 쓰기가 하나다).
+ * 배치 사이에 루프를 비워 준다.
+ *
+ * **같은 시각의 줄을 반쪽만 적지 않는다.** 한 배치의 가장 오래된 시각에 걸친 줄들은 다음 배치로 넘긴다 —
+ * 반쪽만 적으면 그 시각이 「채워진 것」으로 보이면서 일부가 빠진다.
+ *
+ * **몇 줄을 옮겼고 어디까지 왔는지 말한다.** 알리지 않고 절반만 채우면 화면이 「그 앞에는 사건이 없다」고
+ * 말하게 된다.
+ */
+/** 한 번에 읽는 저널 행 수 — 저널 정리와 같은 규율. */
+const READ_BATCH = 5_000;
+/**
+ * 옮기는 중인 트윈의 목표와 지점 — **이 프로세스 안에서만** 든다.
+ *
+ * 테이블에 적지 않는다(사용자 판단, 2026-08-27). 서버가 내려가면 사라지고, 다음에 부르면 처음부터
+ * 다시 읽는다. 그 대가를 아는 채로 두는 것이다.
+ */
+const inFlight = new Map();
+/**
+ * 한 트윈의 저장된 사건을 이 표로 옮긴다 — 예산 안에서.
+ *
+ * 되풀어 부르면 이어서 한다. 넘길 인자가 없다 — 진행 지점을 적어 두기 때문이다.
+ */
+async function backfillSubjects(domainId, instanceId, opts = {}) {
+    const budgetMs = opts.budgetMs ?? 30_000;
+    const startedMs = Date.now();
+    const reg = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance)
+        .findOne({ where: { domain: { id: domainId }, instanceId } })
+        .catch(() => null);
+    if (!reg?.model) {
+        throw new Error(`twin "${instanceId}" is not registered — no model to resolve declared items with`);
+    }
+    const itemOf = (0, item_resolver_js_1.itemResolverFor)(domainId, instanceId, reg.model);
+    if (!itemOf) {
+        (0, log_js_1.twinWarn)(`[twin-subject] "${instanceId}" 선언된 품목이 없어 품목 줄은 만들지 않는다 — 개체·자리·설비 줄만 옮긴다.`);
+    }
+    /*
+     * ── 진행 지점을 **판 안에서만** 든다 (2026-08-27 · 사용자 판단) ────────────────
+     *
+     * 처음에는 테이블에 적었다. 사용자 판단으로 없앴다 — 사건이 들어올 때 파생 테이블도 같이 적히므로,
+     * 옛 사건을 옮기는 일은 새 파생 테이블을 만들 때와 계산 규칙을 고쳐 다시 만들 때뿐이다. 그 두 경우가
+     * 흔하지 않다.
+     *
+     * 대가는 이것이다. 옮기는 중에 서버가 내려가면 그 몫을 다시 읽는다. 335만 건이면 20분쯤이다.
+     *
+     * 그래서 **목표와 지점을 이 프로세스가 든다.** 트윈마다 한 줄이고, 서버가 내려가면 사라진다.
+     */
+    const events = (0, shell_1.getRepository)(twin_event_js_1.TwinEvent);
+    const key = `${domainId}:${instanceId}`;
+    let held = inFlight.get(key);
+    if (!held) {
+        /*
+         * 목표는 **처음 부를 때의 저널 끝**이다. 매번 다시 재면 그 사이에 새 사건이 들어와 끝나지 않는다.
+         * 그 뒤의 사건은 저널을 쓸 때 파생 테이블에도 같이 적히므로 이 작업의 몫이 아니다.
+         */
+        const tip = await events
+            .createQueryBuilder('e')
+            .select('MAX(e.revision)', 'max')
+            .where('e.domain = :domainId', { domainId })
+            .andWhere('e.instanceId = :instanceId', { instanceId })
+            .getRawOne();
+        held = { upToRevision: 0, targetRevision: Number(tip?.max ?? 0) };
+        inFlight.set(key, held);
+    }
+    let read = 0;
+    let written = 0;
+    let paused = false;
+    let cursor = held.upToRevision;
+    const target = held.targetRevision;
+    for (;;) {
+        if (cursor >= target)
+            break;
+        if (Date.now() - startedMs >= budgetMs) {
+            paused = true;
+            break;
+        }
+        const rows = await events
+            .createQueryBuilder('e')
+            .where('e.domain = :domainId', { domainId })
+            .andWhere('e.instanceId = :instanceId', { instanceId })
+            .andWhere('e.revision > :cursor', { cursor })
+            .andWhere('e.revision <= :target', { target })
+            .orderBy('e.revision', 'ASC')
+            .take(READ_BATCH)
+            .getMany();
+        if (!rows.length) {
+            cursor = target;
+            break;
+        }
+        read += rows.length;
+        written += await writeRows(domainId, instanceId, rows, itemOf);
+        cursor = Number(rows[rows.length - 1].revision);
+        /* 진행 지점을 그때그때 든다 — 중간에 멈춰도 다음 호출이 여기서 잇는다(같은 프로세스 안에서). */
+        held.upToRevision = cursor;
+        /* 배치 사이에 루프를 비워 준다 — 이 한 줄이 없으면 나눈 뜻이 없다. */
+        await new Promise(resolve => setImmediate(resolve));
+    }
+    held.upToRevision = cursor;
+    const complete = cursor >= target;
+    /* 다 옮겼으면 들고 있을 이유가 없다 — 다시 부르면 목표를 새로 잡는다(그때는 옮길 것이 없다). */
+    if (complete)
+        inFlight.delete(key);
+    (0, log_js_1.twinLog)(`[twin-subject] backfill "${instanceId}" — 저널 ${read}행을 읽어 ${written}줄 적었다 · ` +
+        `리비전 ${cursor}/${target}` +
+        `${complete ? ' · 다 옮겼다' : paused ? ' · 예산을 다 써서 멈췄다 — 다시 부르면 이어서 한다' : ''}`);
+    return { instanceId, read, written, upToRevision: cursor, targetRevision: target, complete, paused };
+}
+/** 저널 행들을 봉투로 되돌려 적는다 — `payload` 가 봉투 전체다. */
+async function writeRows(domainId, instanceId, rows, itemOf) {
+    return await (0, twin_subject_writer_js_1.writeSubjectRows)(domainId, instanceId, rows.map(r => ({
+        /*
+         * `payload` 가 봉투 전체다(`{ eventId, eventType, eventTime, tenantId, data: {…} }`). 한 겹 더
+         * 감싸면 키가 묻혀 아무것도 찾지 못한다 — 실측으로 825,000행을 읽어 0줄을 적었다.
+         *
+         * 시각과 종류는 승격 컬럼을 믿는다. payload 안의 값과 컬럼이 어긋난 옛 행이 있을 수 있고,
+         * 이 표의 정렬 축은 컬럼이 정본이다.
+         */
+        envelope: { ...(r.payload ?? {}), eventType: r.eventType, eventTime: r.eventTime },
+        revision: Number(r.revision),
+        eventId: r.id
+    })), itemOf);
+}
+//# sourceMappingURL=twin-subject-backfill.js.map

package/dist-server/service/twin-subject/twin-subject-backfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-subject-backfill.js","sourceRoot":"","sources":["../../../server/service/twin-subject/twin-subject-backfill.ts"],"names":[],"mappings":"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","sourcesContent":["import { getRepository } from '@things-factory/shell'\n\nimport { twinLog, twinWarn } from '../../engine/log.js'\nimport { TwinEvent } from '../twin-event/twin-event.js'\nimport { TwinInstance } from '../twin-instance/twin-instance.js'\nimport { TwinSubjectEvent } from './twin-subject-event.js'\nimport { writeSubjectRows } from './twin-subject-writer.js'\nimport { itemResolverFor } from './item-resolver.js'\n\n/*\n * **이미 저장된 사건을 이 표로 옮긴다** — 요청받은 트윈만.\n *\n * ── 왜 기본이 아닌가 ────────────────────────────────────────────────────────\n * 이 표의 규칙은 「앞으로만 채운다」다. 그래야 새 조회 축이 필요할 때마다 3,128만 줄을 다시 만드는\n * 구조가 되지 않는다(설계: read-models.md §4).\n *\n * 그런데 이미 쌓인 트윈에서 이력을 보려면 그 구간이 있어야 한다. 그래서 **부르면 채우는 도구**로 둔다 —\n * 마이그레이션이 아니고, 부팅에 자동으로 돌지도 않는다. 트윈을 지정해 부른다.\n *\n * ── 어디까지 옮겼는지 적어 둔다 (2026-08-27 · 세 번 틀린 뒤) ─────────────────\n * 저장하지 않고 표의 내용으로 진행 지점을 알아내려 했고 세 번 틀렸다.\n *\n *   ① 표의 최대 리비전 뒤부터    앞으로 채워진 줄의 최댓값이 곧 저널의 끝이라 소급을 다 건너뛴다\n *   ② 표의 최소 리비전 앞까지    소급이 1부터 적으면 최솟값이 1이 되어 구간이 0으로 접힌다\n *   ③ 표의 최소 시각 아래로      사건이 시각순으로 오지 않는 트윈에서 곧바로 끝난다\n *\n * ③이 결정적이었다. 승화푸드 커넥터는 과거 기록을 되읽으므로 방금 들어온 사건의 시각이 2024년 10월이다.\n * 그래서 표의 가장 오래된 시각이 이미 저널의 시작과 같아진다.\n *\n * 원인은 하나다. **채워진 것은 구간이 아니라 집합이다.** 리비전으로 보든 시각으로 보든 「어디까지」를\n * 하나의 경계로 말할 수 없다. 그래서 알아내려 하지 않고 **이 프로세스가 든다**(§`inFlight`).\n *\n * 리비전 1부터 순서대로 올라간다. 목표는 **채우기를 시작한 순간의 저널 끝**이다 — 그보다 뒤는 앞으로\n * 채우는 쪽이 이미 적고 있다.\n *\n * ── 규율 ────────────────────────────────────────────────────────────────────\n * **나눠서 옮긴다.** 한 번에 통째로 읽으면 그동안 호스트가 아무 일도 못 한다(sqlite 는 쓰기가 하나다).\n * 배치 사이에 루프를 비워 준다.\n *\n * **같은 시각의 줄을 반쪽만 적지 않는다.** 한 배치의 가장 오래된 시각에 걸친 줄들은 다음 배치로 넘긴다 —\n * 반쪽만 적으면 그 시각이 「채워진 것」으로 보이면서 일부가 빠진다.\n *\n * **몇 줄을 옮겼고 어디까지 왔는지 말한다.** 알리지 않고 절반만 채우면 화면이 「그 앞에는 사건이 없다」고\n * 말하게 된다.\n */\n\n/** 한 번에 읽는 저널 행 수 — 저널 정리와 같은 규율. */\nconst READ_BATCH = 5_000\n\nexport interface BackfillResult {\n  instanceId: string\n  /** 읽은 저널 행 수. */\n  read: number\n  /** 이 표에 적은 줄 수. */\n  written: number\n  /** 여기까지 옮겼다(저널 리비전). */\n  upToRevision: number\n  /** 목표 — 채우기를 시작한 순간의 저널 끝. */\n  targetRevision: number\n  /** 다 옮겼나. */\n  complete: boolean\n  /** 예산을 다 써서 멈췄나. */\n  paused: boolean\n}\n\n/**\n * 옮기는 중인 트윈의 목표와 지점 — **이 프로세스 안에서만** 든다.\n *\n * 테이블에 적지 않는다(사용자 판단, 2026-08-27). 서버가 내려가면 사라지고, 다음에 부르면 처음부터\n * 다시 읽는다. 그 대가를 아는 채로 두는 것이다.\n */\nconst inFlight = new Map<string, { upToRevision: number; targetRevision: number }>()\n\n/**\n * 한 트윈의 저장된 사건을 이 표로 옮긴다 — 예산 안에서.\n *\n * 되풀어 부르면 이어서 한다. 넘길 인자가 없다 — 진행 지점을 적어 두기 때문이다.\n */\nexport async function backfillSubjects(\n  domainId: string,\n  instanceId: string,\n  opts: { budgetMs?: number } = {}\n): Promise<BackfillResult> {\n  const budgetMs = opts.budgetMs ?? 30_000\n  const startedMs = Date.now()\n\n  const reg = await getRepository(TwinInstance)\n    .findOne({ where: { domain: { id: domainId }, instanceId } })\n    .catch(() => null)\n  if (!reg?.model) {\n    throw new Error(`twin \"${instanceId}\" is not registered — no model to resolve declared items with`)\n  }\n  const itemOf = itemResolverFor(domainId, instanceId, reg.model)\n  if (!itemOf) {\n    twinWarn(\n      `[twin-subject] \"${instanceId}\" 선언된 품목이 없어 품목 줄은 만들지 않는다 — 개체·자리·설비 줄만 옮긴다.`\n    )\n  }\n\n  /*\n   * ── 진행 지점을 **판 안에서만** 든다 (2026-08-27 · 사용자 판단) ────────────────\n   *\n   * 처음에는 테이블에 적었다. 사용자 판단으로 없앴다 — 사건이 들어올 때 파생 테이블도 같이 적히므로,\n   * 옛 사건을 옮기는 일은 새 파생 테이블을 만들 때와 계산 규칙을 고쳐 다시 만들 때뿐이다. 그 두 경우가\n   * 흔하지 않다.\n   *\n   * 대가는 이것이다. 옮기는 중에 서버가 내려가면 그 몫을 다시 읽는다. 335만 건이면 20분쯤이다.\n   *\n   * 그래서 **목표와 지점을 이 프로세스가 든다.** 트윈마다 한 줄이고, 서버가 내려가면 사라진다.\n   */\n  const events = getRepository(TwinEvent)\n  const key = `${domainId}:${instanceId}`\n  let held = inFlight.get(key)\n  if (!held) {\n    /*\n     * 목표는 **처음 부를 때의 저널 끝**이다. 매번 다시 재면 그 사이에 새 사건이 들어와 끝나지 않는다.\n     * 그 뒤의 사건은 저널을 쓸 때 파생 테이블에도 같이 적히므로 이 작업의 몫이 아니다.\n     */\n    const tip = await events\n      .createQueryBuilder('e')\n      .select('MAX(e.revision)', 'max')\n      .where('e.domain = :domainId', { domainId })\n      .andWhere('e.instanceId = :instanceId', { instanceId })\n      .getRawOne<{ max: unknown }>()\n    held = { upToRevision: 0, targetRevision: Number(tip?.max ?? 0) }\n    inFlight.set(key, held)\n  }\n\n  let read = 0\n  let written = 0\n  let paused = false\n  let cursor = held.upToRevision\n  const target = held.targetRevision\n\n  for (;;) {\n    if (cursor >= target) break\n    if (Date.now() - startedMs >= budgetMs) {\n      paused = true\n      break\n    }\n    const rows = await events\n      .createQueryBuilder('e')\n      .where('e.domain = :domainId', { domainId })\n      .andWhere('e.instanceId = :instanceId', { instanceId })\n      .andWhere('e.revision > :cursor', { cursor })\n      .andWhere('e.revision <= :target', { target })\n      .orderBy('e.revision', 'ASC')\n      .take(READ_BATCH)\n      .getMany()\n    if (!rows.length) {\n      cursor = target\n      break\n    }\n\n    read += rows.length\n    written += await writeRows(domainId, instanceId, rows, itemOf)\n    cursor = Number(rows[rows.length - 1].revision)\n    /* 진행 지점을 그때그때 든다 — 중간에 멈춰도 다음 호출이 여기서 잇는다(같은 프로세스 안에서). */\n    held.upToRevision = cursor\n    /* 배치 사이에 루프를 비워 준다 — 이 한 줄이 없으면 나눈 뜻이 없다. */\n    await new Promise(resolve => setImmediate(resolve))\n  }\n\n  held.upToRevision = cursor\n  const complete = cursor >= target\n  /* 다 옮겼으면 들고 있을 이유가 없다 — 다시 부르면 목표를 새로 잡는다(그때는 옮길 것이 없다). */\n  if (complete) inFlight.delete(key)\n  twinLog(\n    `[twin-subject] backfill \"${instanceId}\" — 저널 ${read}행을 읽어 ${written}줄 적었다 · ` +\n      `리비전 ${cursor}/${target}` +\n      `${complete ? ' · 다 옮겼다' : paused ? ' · 예산을 다 써서 멈췄다 — 다시 부르면 이어서 한다' : ''}`\n  )\n\n  return { instanceId, read, written, upToRevision: cursor, targetRevision: target, complete, paused }\n}\n\n/** 저널 행들을 봉투로 되돌려 적는다 — `payload` 가 봉투 전체다. */\nasync function writeRows(domainId: string, instanceId: string, rows: TwinEvent[], itemOf?: any): Promise<number> {\n  return await writeSubjectRows(\n    domainId,\n    instanceId,\n    rows.map(r => ({\n      /*\n       * `payload` 가 봉투 전체다(`{ eventId, eventType, eventTime, tenantId, data: {…} }`). 한 겹 더\n       * 감싸면 키가 묻혀 아무것도 찾지 못한다 — 실측으로 825,000행을 읽어 0줄을 적었다.\n       *\n       * 시각과 종류는 승격 컬럼을 믿는다. payload 안의 값과 컬럼이 어긋난 옛 행이 있을 수 있고,\n       * 이 표의 정렬 축은 컬럼이 정본이다.\n       */\n      envelope: { ...((r as any).payload ?? {}), eventType: r.eventType, eventTime: r.eventTime },\n      revision: Number(r.revision),\n      eventId: r.id\n    })),\n    itemOf\n  )\n}\n"]}

package/dist-server/service/twin-subject/twin-subject-event.d.ts

@@ -0,0 +1,14 @@
+import { Domain } from '@things-factory/shell';
+export declare class TwinSubjectEvent {
+    readonly id: string;
+    domain: Domain;
+    domainId?: string;
+    instanceId: string;
+    subjectKind: string;
+    subjectId: string;
+    eventTime: Date;
+    revision: number;
+    eventType: string;
+    eventId?: string;
+    createdAt?: Date;
+}

package/dist-server/service/twin-subject/twin-subject-event.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinSubjectEvent = 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");
+/*
+ * **대상별 사건 목록** — 조회용 파생 표. 사실의 원본은 `twin_events` 다.
+ *
+ * ── 왜 만드나 (2026-08-27 실측) ─────────────────────────────────────────────
+ * 360 화면이 「이 대상의 이력」을 묻고, 그 조회가 64초다. 원인은 「무엇으로 걸러 시각순으로 정렬해
+ * 앞에서 30개」라는 모양에 맞는 목차가 없다는 것이다. 그리고 목차를 얹는 방식으로는 풀리지 않는다.
+ *
+ *   정렬이 목차를 무력화한다      여러 값으로 거르면(IN) 합칠 때 다시 정렬해야 한다
+ *   축이 늘 때마다 목차가 늘어난다  360 의 축 넷을 다 빠르게 하면 `twin_events` 목차가 13개가 된다
+ *   소급 채우기가 매번 든다       목차 하나 만드는 데 3분 36초 · 파일 +2.4GB
+ *   품목 축은 그래도 안 풀린다     저장된 식별자에 품목과 로트가 한 문자열로 붙어 있다
+ *
+ * ── 이 표가 무엇을 담나 ─────────────────────────────────────────────────────
+ * 사건 하나가 가리키는 **대상마다 한 줄**이다. 품목 이동 사건이면 품목·로트·자리로 세 줄이다.
+ * 종류(`subjectKind`)를 값으로 밝히므로 읽는 쪽이 사건 종류표를 들고 있지 않아도 된다. 뜻이
+ * 달라지는 키 칸을 쓰지 않는 이유이고, 그 방식이 틀렸다는 뜻은 아니다 — 정의가 함께 있는
+ * 프레임워크에서는 합리적이다. 이 표는 볼 정의가 없다.
+ *
+ * ── 규칙 넷 (설계: read-models.md §4) ───────────────────────────────────────
+ *   ① 조회는 이 표가 답한다. `twin_events` 에 목차를 얹어 답하지 않는다
+ *   ② **앞으로만 채운다.** 소급하지 않는다 — 새 키가 필요할 때 3,128만 줄을 다시 만들지 않는다
+ *   ③ 준비되지 않은 구간을 화면이 말한다. 비어 있는 것을 「없다」로 그리지 않는다
+ *   ④ 언제든 버릴 수 있다. 사건에서 파생된 값이므로 지워도 사실이 사라지지 않는다
+ *
+ * ── 왜 사건 본문을 베끼지 않나 ──────────────────────────────────────────────
+ * `eventId` 로 원본을 가리키고, 목록을 그리는 데 필요한 값만 함께 둔다(종류·시각·리비전). 본문까지
+ * 베끼면 이 표가 원본만큼 커지고, 원본을 고칠 때 두 곳이 어긋난다.
+ */
+let TwinSubjectEvent = class TwinSubjectEvent {
+};
+exports.TwinSubjectEvent = TwinSubjectEvent;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, type_graphql_1.Field)(type => String, { description: 'Row id.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinSubjectEvent.prototype, "id", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => shell_1.Domain),
+    tslib_1.__metadata("design:type", shell_1.Domain)
+], TwinSubjectEvent.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.domain),
+    tslib_1.__metadata("design:type", String)
+], TwinSubjectEvent.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'The twin instance this row belongs to.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinSubjectEvent.prototype, "instanceId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({
+        description: 'What kind of thing this row points at: item, lot, order, location, equipment or task. The kind is stored as a value so a reader never has to know which event types put what where.'
+    }),
+    tslib_1.__metadata("design:type", String)
+], TwinSubjectEvent.prototype, "subjectKind", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Identifier of that thing, within its kind.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinSubjectEvent.prototype, "subjectId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'When the event happened, by the twin clock. This is the axis the history list is ordered by.' }),
+    tslib_1.__metadata("design:type", Date)
+], TwinSubjectEvent.prototype, "eventTime", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int' }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { description: 'Journal revision of the event — ties this row to its place in the record.' }),
+    tslib_1.__metadata("design:type", Number)
+], TwinSubjectEvent.prototype, "revision", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Event type, so the list can be drawn without reading the journal row.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinSubjectEvent.prototype, "eventType", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Journal row this points at. Null when the journal row has been pruned.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinSubjectEvent.prototype, "eventId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    (0, type_graphql_1.Field)({ description: 'When this row was written.' }),
+    tslib_1.__metadata("design:type", Date)
+], TwinSubjectEvent.prototype, "createdAt", void 0);
+exports.TwinSubjectEvent = TwinSubjectEvent = tslib_1.__decorate([
+    (0, typeorm_1.Entity)()
+    /*
+     * 이 표의 유일한 목차 — 이 순서가 곧 이 표의 존재 이유다.
+     *
+     * 「이 트윈의 이 대상의 것을 최신순으로 30개」가 목차를 위에서 30줄 읽고 끝난다. 정렬이 없다 —
+     * 거르는 값이 하나이고 그 다음이 시각이기 때문이다.
+     */
+    ,
+    (0, typeorm_1.Index)('ix_twin_subject_event_0', (e) => [e.domain, e.instanceId, e.subjectKind, e.subjectId, e.eventTime], { unique: false })
+    /* 보관 상한을 지우는 축 — 「이 트윈에서 오래된 줄」을 찾는다(§`twin-subject-writer` 의 정리). */
+    ,
+    (0, typeorm_1.Index)('ix_twin_subject_event_1', (e) => [e.domain, e.instanceId, e.eventTime], {
+        unique: false
+    }),
+    (0, type_graphql_1.ObjectType)({ description: 'One row per subject an event refers to — the read model behind entity history.' })
+], TwinSubjectEvent);
+//# sourceMappingURL=twin-subject-event.js.map

package/dist-server/service/twin-subject/twin-subject-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-subject-event.js","sourceRoot":"","sources":["../../../server/service/twin-subject/twin-subject-event.ts"],"names":[],"mappings":";;;;AAAA,+CAAqD;AACrD,qCAAgH;AAChH,iDAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAkBI,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;CAmD5B,CAAA;AAnDY,4CAAgB;AAGlB;IAFR,IAAA,gCAAsB,EAAC,MAAM,CAAC;IAC9B,IAAA,oBAAK,EAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;;4CAC/B;AAGnB;IADC,IAAA,mBAAS,EAAC,IAAI,CAAC,EAAE,CAAC,cAAM,CAAC;sCAClB,cAAM;gDAAA;AAGd;IADC,IAAA,oBAAU,EAAC,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;;kDAC7B;AAIjB;IAFC,IAAA,gBAAM,GAAE;IACR,IAAA,oBAAK,EAAC,EAAE,WAAW,EAAE,wCAAwC,EAAE,CAAC;;oDAC/C;AAOlB;IALC,IAAA,gBAAM,GAAE;IACR,IAAA,oBAAK,EAAC;QACL,WAAW,EACT,qLAAqL;KACxL,CAAC;;qDACiB;AAInB;IAFC,IAAA,gBAAM,GAAE;IACR,IAAA,oBAAK,EAAC,EAAE,WAAW,EAAE,4CAA4C,EAAE,CAAC;;mDACpD;AAUjB;IAFC,IAAA,gBAAM,GAAE;IACR,IAAA,oBAAK,EAAC,EAAE,WAAW,EAAE,8FAA8F,EAAE,CAAC;sCAC5G,IAAI;mDAAA;AAIf;IAFC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACvB,IAAA,oBAAK,EAAC,IAAI,CAAC,EAAE,CAAC,kBAAG,EAAE,EAAE,WAAW,EAAE,2EAA2E,EAAE,CAAC;;kDACjG;AAIhB;IAFC,IAAA,gBAAM,GAAE;IACR,IAAA,oBAAK,EAAC,EAAE,WAAW,EAAE,uEAAuE,EAAE,CAAC;;mDAC/E;AAIjB;IAFC,IAAA,gBAAM,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1B,IAAA,oBAAK,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,wEAAwE,EAAE,CAAC;;iDACjG;AAIhB;IAFC,IAAA,0BAAgB,GAAE;IAClB,IAAA,oBAAK,EAAC,EAAE,WAAW,EAAE,4BAA4B,EAAE,CAAC;sCACzC,IAAI;mDAAA;2BAlDL,gBAAgB;IAjB5B,IAAA,gBAAM,GAAE;IACT;;;;;OAKG;;IACF,IAAA,eAAK,EACJ,yBAAyB,EACzB,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,EAC1F,EAAE,MAAM,EAAE,KAAK,EAAE,CAClB;IACD,sEAAsE;;IACrE,IAAA,eAAK,EAAC,yBAAyB,EAAE,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC,EAAE;QAChG,MAAM,EAAE,KAAK;KACd,CAAC;IACD,IAAA,yBAAU,EAAC,EAAE,WAAW,EAAE,gFAAgF,EAAE,CAAC;GACjG,gBAAgB,CAmD5B","sourcesContent":["import { Field, Int, ObjectType } from 'type-graphql'\nimport { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'\nimport { Domain } from '@things-factory/shell'\n\n/*\n * **대상별 사건 목록** — 조회용 파생 표. 사실의 원본은 `twin_events` 다.\n *\n * ── 왜 만드나 (2026-08-27 실측) ─────────────────────────────────────────────\n * 360 화면이 「이 대상의 이력」을 묻고, 그 조회가 64초다. 원인은 「무엇으로 걸러 시각순으로 정렬해\n * 앞에서 30개」라는 모양에 맞는 목차가 없다는 것이다. 그리고 목차를 얹는 방식으로는 풀리지 않는다.\n *\n *   정렬이 목차를 무력화한다      여러 값으로 거르면(IN) 합칠 때 다시 정렬해야 한다\n *   축이 늘 때마다 목차가 늘어난다  360 의 축 넷을 다 빠르게 하면 `twin_events` 목차가 13개가 된다\n *   소급 채우기가 매번 든다       목차 하나 만드는 데 3분 36초 · 파일 +2.4GB\n *   품목 축은 그래도 안 풀린다     저장된 식별자에 품목과 로트가 한 문자열로 붙어 있다\n *\n * ── 이 표가 무엇을 담나 ─────────────────────────────────────────────────────\n * 사건 하나가 가리키는 **대상마다 한 줄**이다. 품목 이동 사건이면 품목·로트·자리로 세 줄이다.\n * 종류(`subjectKind`)를 값으로 밝히므로 읽는 쪽이 사건 종류표를 들고 있지 않아도 된다. 뜻이\n * 달라지는 키 칸을 쓰지 않는 이유이고, 그 방식이 틀렸다는 뜻은 아니다 — 정의가 함께 있는\n * 프레임워크에서는 합리적이다. 이 표는 볼 정의가 없다.\n *\n * ── 규칙 넷 (설계: read-models.md §4) ───────────────────────────────────────\n *   ① 조회는 이 표가 답한다. `twin_events` 에 목차를 얹어 답하지 않는다\n *   ② **앞으로만 채운다.** 소급하지 않는다 — 새 키가 필요할 때 3,128만 줄을 다시 만들지 않는다\n *   ③ 준비되지 않은 구간을 화면이 말한다. 비어 있는 것을 「없다」로 그리지 않는다\n *   ④ 언제든 버릴 수 있다. 사건에서 파생된 값이므로 지워도 사실이 사라지지 않는다\n *\n * ── 왜 사건 본문을 베끼지 않나 ──────────────────────────────────────────────\n * `eventId` 로 원본을 가리키고, 목록을 그리는 데 필요한 값만 함께 둔다(종류·시각·리비전). 본문까지\n * 베끼면 이 표가 원본만큼 커지고, 원본을 고칠 때 두 곳이 어긋난다.\n */\n@Entity()\n/*\n * 이 표의 유일한 목차 — 이 순서가 곧 이 표의 존재 이유다.\n *\n * 「이 트윈의 이 대상의 것을 최신순으로 30개」가 목차를 위에서 30줄 읽고 끝난다. 정렬이 없다 —\n * 거르는 값이 하나이고 그 다음이 시각이기 때문이다.\n */\n@Index(\n  'ix_twin_subject_event_0',\n  (e: TwinSubjectEvent) => [e.domain, e.instanceId, e.subjectKind, e.subjectId, e.eventTime],\n  { unique: false }\n)\n/* 보관 상한을 지우는 축 — 「이 트윈에서 오래된 줄」을 찾는다(§`twin-subject-writer` 의 정리). */\n@Index('ix_twin_subject_event_1', (e: TwinSubjectEvent) => [e.domain, e.instanceId, e.eventTime], {\n  unique: false\n})\n@ObjectType({ description: 'One row per subject an event refers to — the read model behind entity history.' })\nexport class TwinSubjectEvent {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => String, { description: 'Row id.' })\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  domain: Domain\n\n  @RelationId((e: TwinSubjectEvent) => e.domain)\n  domainId?: string\n\n  @Column()\n  @Field({ description: 'The twin instance this row belongs to.' })\n  instanceId: string\n\n  @Column()\n  @Field({\n    description:\n      'What kind of thing this row points at: item, lot, order, location, equipment or task. The kind is stored as a value so a reader never has to know which event types put what where.'\n  })\n  subjectKind: string\n\n  @Column()\n  @Field({ description: 'Identifier of that thing, within its kind.' })\n  subjectId: string\n\n  /*\n   * **타입 이름을 적지 않는다** — `twin-event.ts` 의 `eventTime` 과 같은 이유다.\n   *\n   * `datetime` 은 sqlite·MySQL 의 이름이고 Postgres 는 `timestamp` 만 안다. 다섯 드라이버에 다\n   * 통하는 이름이 없어서, 이름을 고르는 일을 TypeORM 에 맡긴다(TS 타입 `Date` 에서 고른다).\n   */\n  @Column()\n  @Field({ description: 'When the event happened, by the twin clock. This is the axis the history list is ordered by.' })\n  eventTime: Date\n\n  @Column({ type: 'int' })\n  @Field(type => Int, { description: 'Journal revision of the event — ties this row to its place in the record.' })\n  revision: number\n\n  @Column()\n  @Field({ description: 'Event type, so the list can be drawn without reading the journal row.' })\n  eventType: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Journal row this points at. Null when the journal row has been pruned.' })\n  eventId?: string\n\n  @CreateDateColumn()\n  @Field({ description: 'When this row was written.' })\n  createdAt?: Date\n}\n"]}