@things-factory/headless-twin 10.0.14 → 10.0.17

package/server/service/twin-model/twin-model-tree-query.ts

@@ -21,7 +21,7 @@ const { TWIN_RELATIONS, axisInfo } = require('@operato/twin-kernel')
  * 대신 **선언 그래프에서 자기 축으로 돌아오는 두 홉 순환을 찾는다.** 자재만이 아니라 앞으로
  * 같은 모양을 갖는 어떤 축이든 그대로 펼쳐진다.
  *
- * ── 조용히 고르지 않는다 ───────────────────────────────────────────────────────
+ * ── 알리지 않고 고르지 않는다 ───────────────────────────────────────────────────────
  * 순환이 여럿이면 **아무거나 집지 않는다.** 후보를 돌려주고 부르는 쪽이 고르게 한다 — 한쪽을
  * 집으면 역전개(누가 나를 쓰나)를 전개(내가 무엇으로 되나)로 보여 주고도 아무도 모른다.
  */
@@ -102,12 +102,36 @@ export class TwinModelTreeQuery {
     const all = patternsFor(axis)
     if (!all.length) return { axis, itemId, patterns: [], items: [], edges: [], reason: 'no-recursive-relation' }
 
+
     const chosen = inVia && outVia ? all.find(p => p.inVia === inVia && p.outVia === outVia) : all.length === 1 ? all[0] : undefined
     if (!chosen)
       /* 여럿인데 안 고르면 **아무것도 펼치지 않는다.** 한쪽을 집으면 역전개를 전개로 보여 주고도
          아무도 모른다 — 방향이 뒤집힌 BOM 은 틀린 답이 아니라 반대의 답이다. */
       return { axis, itemId, patterns: all, items: [], edges: [], reason: 'ambiguous-pattern' }
 
+    /*
+     * ── ★ **선언에 없는 축은 펼칠 것이 없다** (2026-08-24 실측으로 터짐) ────────
+     *
+     * 이 전개는 **트윈 모델의 선언**을 읽는다(`axisInfo(...).path` 로 모델 안을 찾아 들어간다). 그런데
+     * 커널 카탈로그의 축 중 셋은 **선언되는 것이 아니라 일어나는 것**이다 — `orders`·`tasks`·`items`
+     * 는 사건이 만들고 끝나면 사라진다. 모델이 그 목록을 가질 수 없으므로 `path` 가 비어 있다.
+     *
+     * 그래서 그런 축을 지나려 하면 `at(model, undefined)` 에서 터졌다:
+     *
+     *   Cannot read properties of undefined (reading 'split')
+     *
+     * ★ **터진 것은 요청한 축이 아니라 「거쳐 가는 축」이다.** `locations` 를 물으면 그 순환이
+     * `tasks` 를 거치는데(작업이 `from`·`at` 으로 자리를 두 번 가리킨다) 그 `tasks` 에 경로가 없다.
+     * 그래서 요청한 축만 지켜서는 막히지 않는다 — 둘 다 본다.
+     *
+     * ── 터지지 않게 하는 것만으로는 모자라다 ──────────────────────────────────
+     * 빈 트리를 돌려주면 화면이 **「이어진 것이 없다」**로 읽는다. 그것은 거짓이다 — 작업은 자리를
+     * 가리키고 있고, 다만 **이 질의가 그것을 아는 곳이 아니다**(그 관계는 상태와 저널이 안다).
+     * 그래서 이유를 말한다. 왜 못 하는지 말하지 않는 빈 화면이 이 저장소가 반복해 고친 결함이다.
+     */
+    if (!info.path || !axisInfo(chosen.through)?.path)
+      return { axis, itemId, patterns: all, items: [], edges: [], reason: 'not-declared-in-model' }
+
     const model = inst.model ?? {}
     const throughInfo = axisInfo(chosen.through)
     const listOf = (i: any) => {

package/server/service/twin-model/twin-operation.ts

@@ -11,7 +11,7 @@ import { TwinInstance } from '../twin-instance/twin-instance.js'
  *
  * ── 왜 이 표가 인스펙션의 중심인가 ──────────────────────────────────────────
  * 인스펙션 화면의 존재 이유는 `선언 | 관측` 두 열이고(`plans/twin-inspection.md` §2.4),
- * 그 첫 열이 여기서 온다. 둘째 열은 저널에서 접힌다(`kpi-fold.workTime`).
+ * 그 첫 열이 여기서 온다. 둘째 열은 저널에서 계산된다(`kpi-fold.workTime`).
  * 실적은 보이는데 기준이 안 보이면 "절단이 5분 걸렸다" 를 보고도 빠른지 느린지 알 수 없다.
  *
  * 자리·설비와 같은 규율 — **원본에서 온 캐시**, `sourceRef`·`ingestedAt` 필수,
@@ -83,7 +83,7 @@ export class TwinOperation {
   /**
    * 소요시간 — **ISO 8601 기간 문자열이 정본**(`PT1H10M`).
    *
-   * 분으로 저장하면 `PT1H10M30S` 의 초가 사라지고 그 손실은 조용하다. 사람이 읽을 분은
+   * 분으로 저장하면 `PT1H10M30S` 의 초가 사라지고 그 손실은 들어온 것이 없다. 사람이 읽을 분은
    * 화면이 곁들여 보여 주고, 못 읽는 값은 `—` 로 낸다(0 으로 채우면 "즉시 끝나는 공정" 이라는 거짓).
    */
   @Column({ nullable: true })

package/server/service/twin-space/move-space.ts

@@ -15,12 +15,12 @@
  *  · `TwinSpaceRepresentation`(지도·이미지·보드)     → **남는다.** 표현도 공간의 것이다.
  *
  * 그래서 옮기기는 이력 이전이 아니라 **소속 갱신**이다(`instance.spaceId` + `model.spaceId`).
- * 대신 공간에 매인 것들과의 연결이 끊길 수 있고, 그것을 **조용히 넘기지 않는 것**이 이 모듈의 일이다.
+ * 대신 공간에 매인 것들과의 연결이 끊길 수 있고, 그것을 **알리지 않고 넘기지 않는 것**이 이 모듈의 일이다.
  *
  * ── 거절과 경고를 가른다 ────────────────────────────────────────────────────
  * 거절: 되돌릴 수 없거나 뜻이 성립하지 않는 것(없는 공간·같은 공간·벤치 사본).
  * 경고: 사용자가 알고 나면 정당할 수 있는 것(구역 소속이 끊긴다·시간대가 다르다·옛 표현이 남는다).
- * 경고를 거절로 올리면 정당한 이전을 막고, 거절을 경고로 낮추면 조용한 사고가 된다.
+ * 경고를 거절로 올리면 정당한 이전을 막고, 거절을 경고로 낮추면 들어온 것이 없는 사고가 된다.
  */
 
 /** 옮길 수 없는 이유 — 언어 중립 코드(발견 오류·인제스트 거절과 같은 규약). */
@@ -175,7 +175,7 @@ export function judgeMoveTwinSpace(input: MoveSpaceInput): MoveSpaceJudgement {
  *  · 구역·표현은 옛 현장에 남는다 → 그 화면에서 이 트윈이 사라진다.
  *  · **볼 무대가 없어진다** — 현장 현황(지도·보드)은 현장의 표현으로 그리므로, 뗀 트윈은 목록과
  *    조회 화면에서만 보인다. 이것을 말하지 않으면 사용자는 트윈이 고장 났다고 읽는다.
- *  · 시간 기준(`utcOffsetMinutes`)은 **옛 현장의 것으로 남는다.** 지우면 조용히 UTC 로 읽히므로
+ *  · 시간 기준(`utcOffsetMinutes`)은 **옛 현장의 것으로 남는다.** 지우면 알리지 않고 UTC 로 읽히므로
  *    그쪽이 더 위험하다 — 남기고 그 사실을 말한다.
  */
 

package/server/service/twin-space/representation-role.ts

@@ -0,0 +1,15 @@
+/*
+ * 표현이 무엇을 위한 것인가 — **닫힌 목록** (2026-08-27 · 사용자 지시).
+ *
+ *   index      표현 목록에 나온다. 비어 있으면 이것이다(흔한 쪽을 기본으로 둔다)
+ *   derived    다른 표현에서 열린다(팝업·드릴 대상). 목록에서는 접어 세어 보인다 — 감추지 않는다
+ *
+ * 열어 두면 넣는 쪽마다 다른 이름을 쓰고, 그러면 화면이 어느 이름을 목록에 넣어야 하는지 알 수 없다.
+ * 늘려야 하면 이 목록에 더한다.
+ *
+ * ── 왜 엔티티가 아니라 이 파일인가 ──────────────────────────────────────────
+ * 엔티티에는 데코레이터가 있어서 테스트가 그 파일을 읽을 수 없다(런타임의 타입 제거가 데코레이터를
+ * 파싱하지 못한다). 값으로 확인해야 하는 것은 데코레이터 없는 파일에 둔다.
+ */
+export const REPRESENTATION_ROLES = ['index', 'derived'] as const
+export type RepresentationRole = (typeof REPRESENTATION_ROLES)[number]

package/server/service/twin-space/space-integrity.ts

@@ -42,7 +42,7 @@ export type SpaceIntegrityCode =
    *
    * 커널은 모르는 `eventType` 을 버리고(전방 호환) 종류별로 센다(`state.unhandled`). 그 수가 0이
    * 아니면 둘 중 하나다: 커넥터가 엉뚱한 트윈에 붙었거나(예: `energy.*` 가 창고 트윈으로), 커널이
-   * 낡아 새 어휘를 모른다. 둘 다 사람이 손봐야 하는 것이고, 조용히 두면 「정상인데 빈」 트윈이 된다.
+   * 낡아 새 어휘를 모른다. 둘 다 사람이 손봐야 하는 것이고, 알리지 않고 두면 「정상인데 빈」 트윈이 된다.
    */
   | 'twin-unhandled-vocabulary'
 

package/server/service/twin-space/twin-space-representation.ts

@@ -48,6 +48,43 @@ export class TwinSpaceRepresentation {
   @Field({ nullable: true, description: 'Whether this is the primary representation.' })
   isPrimary?: boolean
 
+  /*
+   * ── 묶는 이름 · 목록에 나오는지 (2026-08-27 · 사용자 지시) ──────────────────
+   *
+   * 표현이 많아지면 목록만으로는 관리가 안 된다는 요구다.
+   *
+   * `group` 을 **자유 문자열**로 둔다. 묶는 축이 현장마다 다르다(건물별·용도별·층별). 고정 목록으로
+   * 두면 현장마다 맞지 않는다. 별도 표로 올리지 않는 이유는 그룹에 붙을 속성이 아직 없다는 것이고,
+   * 생기면 그때 올린다.
+   *
+   * **그룹 자체의 순서는 컬럼으로 두지 않는다.** 그 그룹에 속한 `seq` 의 최솟값이 그 순서다 —
+   * 화면이 계산한다. 컬럼을 두면 그룹 이름을 바꿀 때 두 곳을 맞춰야 한다.
+   */
+  @Column({ nullable: true })
+  @Field({
+    nullable: true,
+    description:
+      'Free-form group name for arranging a long representation list. Sites group differently (by building, by purpose, by floor), so this is not a fixed vocabulary. The order of the groups themselves is not stored: it is the smallest seq within each group, computed where the list is drawn.'
+  })
+  group?: string
+
+  /*
+   * 목록에 나올 것과 다른 표현에서 열리는 것을 가른다.
+   *
+   * `isPrimary` 에 얹지 않는다 — 그것은 「현장 현황에 나올 하나」를 정하는 다른 질문이다. 하나의 칸이
+   * 두 질문에 답하면 한쪽을 고칠 때 다른 쪽이 오류 없이 바뀐다.
+   *
+   * **없으면 `index` 다.** 그 값이 흔한 쪽이라 비어 있는 것을 기본으로 읽는다. 대신 값이 있을 때는
+   * 아는 값이어야 한다 — 모르는 값을 그냥 두면 화면이 그것을 어느 쪽으로도 그리지 못한다.
+   */
+  @Column({ nullable: true })
+  @Field({
+    nullable: true,
+    description:
+      'What this representation is for: "index" (default when absent — it appears in the representation list) or "derived" (it is opened from another representation, such as a popup or drill target, and is folded out of the list rather than hidden). Kept separate from isPrimary, which answers a different question: which single representation stands for the site.'
+  })
+  role?: string
+
   @Column({ type: 'simple-json', nullable: true })
   @Field(type => ScalarObject, { nullable: true, description: 'Type config: model {boardId} / image {attachmentId|boardId,width,height} / map {center,zoom,provider}.' })
   config?: any

package/server/service/twin-space/twin-space-resolver.ts

@@ -5,6 +5,7 @@ import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinSpace } from './twin-space.js'
 import { TwinSpaceRepresentation } from './twin-space-representation.js'
+import { REPRESENTATION_ROLES } from './representation-role.js'
 import { TwinSpaceArea } from './twin-space-area.js'
 import { TwinArea } from './twin-area.js'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
@@ -74,11 +75,18 @@ export class TwinSpaceResolver {
     const domainId = context.state.domain.id
     const r = await getRepository(TwinSpace).findOne({ where: { domain: { id: domainId }, spaceId } })
     if (!r) return null
-    const reps = await getRepository(TwinSpaceRepresentation).find({ where: { domain: { id: domainId }, space: { id: r.id } }, order: { seq: 'ASC' } })
+    /*
+     * 묶은 이름 다음에 순서로 정렬한다. `group` 이 비어 있는 행이 앞에 오는지 뒤에 오는지는 드라이버마다
+     * 다르므로 그 순서에 기대지 않는다 — 화면이 다시 묶는다(UX 레인과 그렇게 정했다).
+     */
+    const reps = await getRepository(TwinSpaceRepresentation).find({
+      where: { domain: { id: domainId }, space: { id: r.id } },
+      order: { group: 'ASC', seq: 'ASC' }
+    })
     const representations: any[] = []
     for (const rep of reps) {
       const areas = await getRepository(TwinSpaceArea).find({ where: { domain: { id: domainId }, representation: { id: rep.id } }, order: { createdAt: 'ASC' } })
-      representations.push({ id: rep.id, type: rep.type, name: rep.name, seq: rep.seq, isPrimary: rep.isPrimary, config: rep.config, areas: areas.map(a => ({ id: a.id, name: a.name, type: a.type, geometry: a.geometry, drillTo: a.drillTo, binding: a.binding, style: a.style })) })
+      representations.push({ id: rep.id, type: rep.type, name: rep.name, seq: rep.seq, group: rep.group, role: rep.role, isPrimary: rep.isPrimary, config: rep.config, areas: areas.map(a => ({ id: a.id, name: a.name, type: a.type, geometry: a.geometry, drillTo: a.drillTo, binding: a.binding, style: a.style })) })
     }
     return { spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, extentX: r.extentX, extentY: r.extentY, representations }
   }
@@ -106,7 +114,7 @@ export class TwinSpaceResolver {
    * 예전에는 `Boolean` 을 돌려주고 거절은 **한국어 문장을 냈다.** 두 가지가 틀렸다:
    *  ① 서버가 화면의 말을 정했다 — 일본어·스페인어 사용자에게 한국어가 새어 나간다.
    *  ② 오류를 낸 예외를 화면이 받지 않아 **아무 일도 없는 것처럼** 보였다. 사용자는 삭제를 눌렀고
-   *     화면은 그대로였다. 거절을 조용히 하는 것은 실패보다 나쁘다.
+   *     화면은 그대로였다. 거절을 알리지 않고 하는 것은 실패보다 나쁘다.
    * 이제 `{ok, errorCode, errorParams}` 로 낸다 — 화면이 `twin.compose.del.<code>` 로 말을 만든다.
    */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
@@ -268,7 +276,7 @@ export class TwinSpaceResolver {
     if (dryRun) return { ok: true, dryRun: true, warnings: judgement.warnings }
 
     /* 두 곳을 함께 비운다 — 레지스트리와 model 이 어긋나면 어느 쪽이 사실인지 알 수 없다.
-       시간 기준(utcOffsetMinutes)은 **남긴다**: 지우면 조용히 UTC 로 읽힌다(판정이 그렇게 말했다). */
+       시간 기준(utcOffsetMinutes)은 **남긴다**: 지우면 알리지 않고 UTC 로 읽힌다(판정이 그렇게 말했다). */
     const { spaceId: _dropped, ...model } = (inst?.model as any) ?? {}
     await instRepo.update({ id: (inst as any).id }, { spaceId: null as any, model })
 
@@ -348,7 +356,7 @@ export class TwinSpaceResolver {
         const model: any = i.model ?? {}
         /*
          * 어휘가 맞는지는 **실행 중인 트윈만** 답할 수 있다 — 커널이 무엇을 버렸는지는 런타임의 사실이다.
-         * 정지한 트윈은 `undefined`(모른다)로 둔다. 저널을 다시 접어 알아내지는 않는다: 이 질의는
+         * 정지한 트윈은 `undefined`(모른다)로 둔다. 저널을 다시 계산해 알아내지는 않는다: 이 질의는
          * 테넌트 전체를 훑으므로 트윈마다 폴드를 걸면 정합성 점검이 가장 무거운 질의가 된다.
          */
         const live: any = TwinEngine.isRunning(domainId, i.instanceId)
@@ -389,7 +397,7 @@ export class TwinSpaceResolver {
    *
    * 폴리곤이 없는 구역·개체를 가리키는 것은 **고치지 않는다.** 그 도형을 지워야 하는지, 트윈을 다시
    * 데려와야 하는지, 구역을 다시 그려야 하는지는 사람이 정할 일이다 — 기계가 고르면 사용자가 그린
-   * 도형이 조용히 사라진다.
+   * 도형이 오류 없이 사라진다.
    */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, {
@@ -497,7 +505,31 @@ export class TwinSpaceResolver {
     if (!space) return { ok: false, error: `space not found: ${spaceId}` }
     const repo = getRepository(TwinSpaceRepresentation)
     const existing = rep?.id ? await repo.findOne({ where: { id: rep.id } }) : null
-    const saved = await repo.save(repo.create({ ...(existing ?? {}), domain: { id: domainId } as any, space: { id: space.id } as any, type: rep.type, name: rep.name, seq: rep.seq ?? 0, isPrimary: !!rep.isPrimary, config: rep.config }))
+    /*
+     * `role` 은 닫힌 값이다 — 모르는 값을 그냥 저장하면 화면이 그것을 어느 쪽으로도 그리지 못하고,
+     * 그 표현이 목록에서 오류 없이 사라진다. 비어 있는 것은 `index` 를 뜻하므로 그대로 둔다.
+     */
+    const role = rep.role == null || String(rep.role).trim() === '' ? undefined : String(rep.role).trim()
+    if (role && !(REPRESENTATION_ROLES as readonly string[]).includes(role)) {
+      return { ok: false, error: `unknown representation role "${role}" — one of: ${REPRESENTATION_ROLES.join(', ')}` }
+    }
+    /* 묶는 이름은 자유 문자열이다. 다만 공백만 있는 값은 「묶이지 않음」과 같으므로 비운다. */
+    const group = rep.group == null || String(rep.group).trim() === '' ? undefined : String(rep.group).trim()
+
+    const saved = await repo.save(
+      repo.create({
+        ...(existing ?? {}),
+        domain: { id: domainId } as any,
+        space: { id: space.id } as any,
+        type: rep.type,
+        name: rep.name,
+        seq: rep.seq ?? 0,
+        isPrimary: !!rep.isPrimary,
+        config: rep.config,
+        group: group ?? null,
+        role: role ?? null
+      } as Partial<TwinSpaceRepresentation>)
+    )
     return { ok: true, id: saved.id }
   }
 

package/server/service/twin-structure/twin-structure.ts

@@ -9,15 +9,15 @@ import { modelColumnTransformer } from '../../engine/model-vocabulary.js'
  * TwinStructure — **한 트윈이 거쳐 온 공장 구조들.** 리비전 하나가 그 시절의 공장이다.
  *
  * ── 왜 필요한가: 역사를 잃거나 거짓말을 하거나 ──────────────────────────────
- * 공장은 바뀐다. 도장 부스를 넷 더 놓고, 라인을 하나 접는다. 그런데 지금까지는 구조 서명이 바뀌면
+ * 공장은 바뀐다. 도장 부스를 넷 더 놓고, 라인 하나를 닫는다. 그런데 지금까지는 구조 서명이 바뀌면
  * **그 트윈의 저널을 통째로 지우는 것**이 유일한 길이었다. 안 지우면 옛 이벤트를 새 공장에 대고
- * 접게 되어 이력이 거짓말을 하기 때문이다 — 부스가 둘이던 시절의 사실을 여섯 개짜리 공장에 접으면
+ * 계산하게 되어 이력이 거짓말을 하기 때문이다 — 부스가 둘이던 시절의 사실을 여섯 개짜리 공장에 계산하면
  * 그때 없던 부스에서 일이 있었던 것처럼 보인다.
  *
  * 그래서 선택지가 둘뿐이었다: **역사를 잃거나, 거짓말을 하거나.**
  *
  * 셋째 길이 이 표다. 이벤트가 `structureRev` 로 자기 구조를 달고 다니고, 재생은 구조가 바뀌는
- * 지점에서 전환한 뒤 이어 접는다(`replaySegments`). 이력은 "그때 그 공장의 사실" 로 계속 읽힌다.
+ * 지점에서 전환한 뒤 이어서 계산한다(`replaySegments`). 이력은 "그때 그 공장의 사실" 로 계속 읽힌다.
  *
  * ── 왜 model 를 통째로 담나 ─────────────────────────────────────────────────
  * 재생하려면 **그때의 토폴로지 전체**가 필요하다. 차이(diff)만 담으면 리비전 1부터 다시 계산해 쌓아야

package/server/service/twin-subject/event-subjects.ts

@@ -0,0 +1,155 @@
+/*
+ * **이 사건은 무엇에 대한 것인가** — 사건 하나에서 가리키는 대상들을 뽑는다.
+ *
+ * ── 왜 필요한가 (2026-08-27 실측) ───────────────────────────────────────────
+ * 360 화면이 「이 대상의 이력」을 묻는다. 그 조회가 64초다. 대상으로 걸러 시각순으로 정렬하는 목차가
+ * 없기 때문이고, 목차를 얹어도 풀리지 않는다.
+ *
+ *   부분일치(지금 화면)      63.998초   앞에 와일드카드가 붙어 목차를 쓸 수 없다
+ *   정확일치로 바꾸면        67.316초 · 0건   품목 하나에 로트가 여럿이라 성립하지 않는다
+ *   앞부분 범위로 바꾸면     68.402초   목차는 쓰지만 정렬 때문에 맞는 행을 다 가져온다
+ *
+ * 저장된 식별자에 품목과 로트가 한 문자열로 붙어 있는 것이 그 원인이다.
+ *
+ *   https://seunghwa.net/class/product-M0000618-lot-L2604100071
+ *
+ * 그래서 문자열을 자르는 대신 **대상마다 한 줄**을 적는다. 같은 사건이 품목과 로트를 함께 가리키면
+ * 두 줄이다. 자를 규칙이 필요 없다 — 넣는 쪽이 이미 둘을 안다.
+ *
+ * ── 왜 「뜻이 달라지는 키 칸」이 아닌가 ─────────────────────────────────────
+ * `key01~05` 처럼 칸을 두고 사건 종류에 따라 뜻을 달리 쓰는 방식을 **이 표에는** 쓰지 않는다.
+ *
+ * 그 방식 자체가 틀린 것은 아니다. 데이터셋마다 정의가 따로 있는 프레임워크에서는 합리적이다 — 읽는
+ * 쪽이 그 정의를 보고 해석한다. 우리 저널은 표 하나를 화면 여럿이 읽고 볼 정의가 없다. 그래서
+ * 「M0000438 을 찾아 줘」가 어떤 줄에서는 품목, 다른 줄에서는 오더가 되고, 묻는 쪽이 사건 종류마다
+ * 어느 칸에 무엇이 들어가는지 외워야 한다.
+ *
+ * **종류를 값으로 밝힌다.** 그러면 읽는 쪽이 사건 종류표를 들고 있지 않아도 된다.
+ *
+ * ── 왜 순수 모듈인가 ────────────────────────────────────────────────────────
+ * 기록 경로에서 불리므로 DB·데코레이터를 알지 않는다. 그래야 테스트가 값으로 확인할 수 있다
+ * (`twin-event-keys` 와 같은 이유다).
+ *
+ * 설계: `operato-twin/design/plans/read-models.md`
+ */
+import { twinEventKeys } from '../twin-event/twin-event-keys.js'
+
+/**
+ * 대상의 종류 — **닫힌 목록**이다.
+ *
+ * 열어 두면 넣는 쪽마다 다른 이름을 쓰게 되고(설비를 세 가지 이름으로 부르는 식), 그러면 조회가
+ * 어느 이름으로 물어야 하는지 알 수 없다. 늘려야 하면 이 목록에 더한다.
+ *
+ *   item        선언된 품목. 로트 여럿이 같은 품목을 가리킨다
+ *   lot         개체 하나. 저장된 식별자 그대로다
+ *   order       오더
+ *   location    자리
+ *   equipment   설비
+ *   task        작업
+ */
+export const SUBJECT_KINDS = ['item', 'lot', 'order', 'location', 'equipment', 'task'] as const
+export type SubjectKind = (typeof SUBJECT_KINDS)[number]
+
+export interface EventSubject {
+  kind: SubjectKind
+  id: string
+}
+
+/**
+ * 개체 식별자에서 **선언된 품목**을 찾아 주는 함수 — 부르는 쪽이 넘긴다.
+ *
+ * 이 모듈이 문자열을 자르지 않는 이유는 그 규칙이 연결된 시스템마다 다르기 때문이다. 어느 부호가
+ * 로트를 가리키는지 커널 계약이 정한 적이 없고, chef 의 `-lot-` 을 여기에 굳히면 이 파일이 그
+ * 시스템 위에 서게 된다(`item-ref.ts` 가 같은 판단을 적어 두었다).
+ *
+ * 그래서 판정은 **그 트윈의 선언**과 견주어 하고(`resolveByDeclaration`), 그 선언을 아는 것은
+ * 부르는 쪽이다. 답하지 못하면 `undefined` — 그때는 품목 줄을 만들지 않는다. 짐작으로 이으면 남의
+ * 품목 이력에 이 사건이 섞인다.
+ */
+export type ItemResolver = (epc: string) => string | null | undefined
+
+/** 컬럼 길이 상한 — `twin-event-keys` 와 같은 값이다(같은 표에 나란히 서는 값이므로). */
+const MAX_ID = 255
+
+function put(out: EventSubject[], kind: SubjectKind, raw: unknown): void {
+  if (raw === undefined || raw === null) return
+  const id = String(raw).trim()
+  if (!id || id.length > MAX_ID) return
+  /* 같은 대상을 두 번 적지 않는다 — 사건 하나에 같은 자리가 두 번 실려 올 수 있다. */
+  if (out.some(s => s.kind === kind && s.id === id)) return
+  out.push({ kind, id })
+}
+
+/**
+ * 사건 하나가 가리키는 대상들 — 없으면 빈 배열이다.
+ *
+ * 승격된 검색 키(`twinEventKeys`)를 그대로 쓴다. 그 함수가 이미 사건 종류별로 어디에서 값을 꺼낼지
+ * 알고 있으므로, 여기서 다시 판단하면 두 곳이 어긋난다.
+ *
+ * **작업은 승격 키에 없어서 봉투에서 직접 읽는다.** 승격 컬럼을 늘리는 것은 이 작업의 범위가 아니다
+ * (그것이 바로 이 파생 표로 대신하려는 일이다).
+ */
+export function subjectsOf(envelope: any, opts?: { itemOf?: ItemResolver }): EventSubject[] {
+  const keys = twinEventKeys(envelope)
+  const out: EventSubject[] = []
+
+  /*
+   * ── 개체로 온 것과 클래스로 온 것을 갈라 적는다 (2026-08-27 실측) ────────────
+   *
+   * `epcOf` 는 셋을 한 칸에 담는다 — `epcList[0]` · `parentID` · `quantityList[0].epcClass`.
+   * 승격 컬럼이 하나라서 그렇게 되어 있고, 그 칸으로는 「개체인가 클래스인가」를 알 수 없다.
+   *
+   * 실측한 chef 의 사건 하나가 그 경우다. 물건을 개체로 세지 않고 무게로 담는 현장이라 `epcList` 가
+   * 비어 있고 `quantityList` 에 클래스가 있다.
+   *
+   *   epcList     []
+   *   quantityList [{ epcClass: 'https://…/product-M0000879', quantity: 11797.6, uom: 'KGM' }]
+   *
+   * 그것을 로트로 적으면 뜻이 틀린다 — 개체가 아니라 품목이다. 이 표는 종류를 값으로 밝히므로
+   * 갈라 적을 수 있다.
+   */
+  const d = envelope?.data ?? envelope ?? {}
+  const instanceEpc = d.epcList?.[0] ?? d.parentID
+  const classEpc = d.quantityList?.[0]?.epcClass
+
+  if (instanceEpc) {
+    /* 개체는 저장된 식별자 그대로다 — 자르지 않는다. */
+    put(out, 'lot', instanceEpc)
+    /*
+     * 품목은 선언과 견주어 찾는다. 답이 개체 식별자와 같으면 품목을 찾지 못한 것이므로 줄을 만들지
+     * 않는다 — `itemRefOf` 는 URI 세계에서 문자열을 그대로 돌려주기 때문에 그 값이 그대로 올 수 있다.
+     */
+    const item = opts?.itemOf?.(String(instanceEpc))
+    if (item && item !== instanceEpc) put(out, 'item', item)
+  }
+  if (classEpc) {
+    /*
+     * 클래스로 온 것은 개체 줄을 만들지 않는다 — 그 사건에 개체가 없다. 품목 줄만 만든다.
+     *
+     * 선언과 견주어 품목을 찾고, 찾지 못하면 클래스 문자열을 그대로 품목으로 쓴다. 클래스는 이미 품목을
+     * 가리키는 값이므로 그것이 짐작이 아니다(개체 식별자를 그대로 품목으로 쓰는 것과 다르다).
+     */
+    const item = opts?.itemOf?.(String(classEpc)) ?? null
+    put(out, 'item', item || classEpc)
+  }
+  put(out, 'order', keys.orderId)
+  put(out, 'location', keys.locationId)
+  put(out, 'equipment', keys.moverId)
+
+  const data = envelope?.data
+  put(out, 'task', data?.taskId)
+  /*
+   * ── 작업이 오간 두 자리도 적는다 ────────────────────────────────────────────
+   *
+   * 승격 컬럼(`locationId`)은 EPCIS 자리만 담는다(`readPoint` · `bizLocation` · `location`). 작업이
+   * A 에서 B 로 갈 때 그 컬럼에는 **둘 중 하나만** 넣을 수 있어서 아무것도 넣지 않는다.
+   *
+   * 여기서는 둘 다 적는다. 이것이 승격 컬럼과의 어긋남이 아니라 **이 표가 할 수 있는 일**이다 —
+   * 자리 하나에 줄 하나이므로 두 자리를 함께 담는다. 「그 자리에서 무슨 일이 있었나」를 묻는 화면은
+   * 출발지와 도착지를 둘 다 그 자리의 사건으로 본다.
+   */
+  put(out, 'location', data?.fromNode)
+  put(out, 'location', data?.toNode)
+
+  return out
+}

package/server/service/twin-subject/index.ts

@@ -0,0 +1,10 @@
+import { TwinSubjectEvent } from './twin-subject-event.js'
+import { TwinSubjectQuery, TwinSubjectMutation } from './twin-subject-query.js'
+
+export const entities = [TwinSubjectEvent]
+export const resolvers = [TwinSubjectQuery, TwinSubjectMutation]
+export { TwinSubjectEvent, TwinSubjectQuery, TwinSubjectMutation }
+export * from './event-subjects.js'
+export * from './item-resolver.js'
+export * from './twin-subject-writer.js'
+export * from './twin-subject-backfill.js'

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

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

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

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