@things-factory/headless-twin 10.0.15 → 10.0.18

package/server/engine/warm-start.ts

@@ -5,7 +5,7 @@
  * ── 왜 떼어냈나 ─────────────────────────────────────────────────────────────
  * 이 판정이 틀리면 증상이 정반대 두 방향으로 나온다: 주입해야 할 때 안 주입하면 **있는 재고가 0 으로**
  * 보이고(2026-07-31 hatiolab-wms: 저널에 입고 540·출고 94 인데 재고 화면이 비어 있었다), 심지
- * 말아야 할 벤치에 주입하면 **용량 측정이 오염된다.** 둘 다 조용히 틀리는 종류라 규칙을 고정한다.
+ * 말아야 할 벤치에 주입하면 **용량 측정이 오염된다.** 둘 다 알리지 않고 틀리는 종류라 규칙을 고정한다.
  *
  * ── 오더를 버리던 전제가 낡았다 (2026-08-05) ────────────────────────────────
  * 예전 주석은 "스냅샷의 오더에는 progress 밖에 없어서 역산하면 없는 숫자를 지어내는 셈이므로
@@ -17,7 +17,7 @@
  * `StateProjector` 다. 사람·자산·작업도 같은 스냅샷에 있고 커널이 심을 수 있는데 넘기지 않고 있었다.
  * 그래서 씨앗을 **관측 스냅샷 전체**로 넓힌다.
  *
- * 다만 넓히면서 **조용한 누락을 만들지 않는다.** 원값이 없는 오더는 커널이 걸러 내므로(지어내지
+ * 다만 넓히면서 **들어온 것이 없는 누락을 만들지 않는다.** 원값이 없는 오더는 커널이 걸러 내므로(지어내지
  * 않는다), 그 수를 여기서 세어 호출부가 말할 수 있게 한다. 세지 않으면 "주문이 없다" 와 "주문을
  * 못 심었다" 가 화면에서 같아진다.
  */
@@ -95,11 +95,11 @@ const looksLikeState = (x: any): boolean =>
   !!x && typeof x === 'object' && ['locations', 'items', 'equipment', 'orders', 'tasks', 'persons', 'assets', 'acked'].some(k => k in x)
 
 /**
- * 봉투를 벗긴다 — **체크포인트가 겹포장돼 복원이 조용히 죽던 자리.**
+ * 봉투를 벗긴다 — **체크포인트가 겹포장돼 복원이 알리지 않고 죽던 자리.**
  *
  * `TwinEngine.snapshot()` 은 라이브에서는 상태를, 시뮬에서는 `runtime.resync()` 봉투(`{revision,state}`)를
  * 돌려준다. 그 봉투를 다시 `{revision, state}` 로 감싸 캐시에 넣었으므로, 꺼낸 `state` 는 축이 하나도
- * 없는 껍데기였다 → `planWarmStart` 가 "심을 것이 없다" 로 판정하고 **조용히** 넘어갔다. 저널에 수천 건이
+ * 없는 껍데기였다 → `planWarmStart` 가 "심을 것이 없다" 로 판정하고 **알리지 않고** 넘어갔다. 저널에 수천 건이
  * 있고 캐시도 최신인데 트윈이 빈 채로 떴다(오류도 로그도 없다).
  *
  * 반환 모양을 통일하는 것이 뿌리 수정이지만, 그 값은 State 구독 페이로드로도 나가므로 클라이언트 계약을
@@ -128,7 +128,7 @@ export function planWarmStart(state: ObservedState | null | undefined, purpose:
   /* 벤치 판정이 먼저다 — 상태가 있든 없든 벤치에는 주입하지 않는다는 사실이 바뀌지 않는다. */
   if (purpose === 'bench') return { action: 'skip', reason: 'bench' }
   if (!state) return { action: 'skip', reason: 'no-state' }
-  /* 봉투가 들어오면 스스로 벗는다 — 호출부가 한 곳이라도 잊으면 그 경로가 조용히 죽는다(실제로 그랬다). */
+  /* 봉투가 들어오면 스스로 벗는다 — 호출부가 한 곳이라도 잊으면 그 경로가 알리지 않고 죽는다(실제로 그랬다). */
   state = unwrapState(state)
 
   const locations = arr(state.locations)
@@ -191,7 +191,7 @@ export function planWarmStart(state: ObservedState | null | undefined, purpose:
  * 곧 정정하므로, 심으면 **떠난 물건이 되살아나는** 위험만 남는다(그래서 `startLive` 는 오랫동안 아무것도
  * 심지 않았다).
  *
- * 그런데 원천이 **애초에 다시 말해 주지 않는 축**이 있다. 우리가 접어 만든 것들이다:
+ * 그런데 원천이 **애초에 다시 말해 주지 않는 축**이 있다. 우리가 계산해 만든 것들이다:
  *  · 확인(ack)·조건이 처음 성립한 시각 — 사람이 한 일과 우리가 기억한 시각
  *  · 에너지의 열린 구간 누적·적산 기준점·관측 이후 최대 — SCADA 는 「이번 15분에 지금까지 얼마」를 모른다
  *

package/server/index.ts

@@ -32,7 +32,7 @@ process.on('bootstrap-module-start' as any, async ({ app, config, client }: any)
      * 실측: 개발 저널이 시간당 581,794행 · 0.85GB(하루 20GB) 로 자랐고 지우는 것이 없었다. 그런데
      * 「며칠까지 남기나」는 **배포마다 갈리는 사실**이다 — 개발은 짧아도 되고 실증은 길어야 한다.
      *
-     * 선언이 없으면 **아무것도 지우지 않는다.** 조용히 지우는 편이 조용히 쌓는 것보다 나쁘다.
+     * 선언이 없으면 **아무것도 지우지 않는다.** 알리지 않고 지우는 편이 알리지 않고 쌓는 것보다 나쁘다.
      * 값은 스냅샷 TTL(7일)보다 짧을 수 없다 — 엔진이 그것을 올려 주고 그 사실을 말한다.
      */
     /*

package/server/migrations/1786000000000-RenameTwinInstanceBoardToModel.ts

@@ -17,7 +17,7 @@ import { MigrationInterface, QueryRunner } from 'typeorm'
  *
  * ── 멱등 ──────────────────────────────────────────────────────────────────────
  * 이미 `model` 이 있으면(엔티티 선언 + synchronize 가 먼저 지나간 경우) 아무것도 하지 않는다.
- * 그 경우 옛 컬럼이 남아 있을 수 있는데 **지우지 않는다** — 값이 든 컬럼을 마이그레이션이 조용히
+ * 그 경우 옛 컬럼이 남아 있을 수 있는데 **지우지 않는다** — 값이 든 컬럼을 마이그레이션이 알리지 않고
  * 버리면 안 된다. 남은 컬럼의 처분은 사람이 확인한 뒤의 일이다.
  */
 const TABLE_NAME = 'twin_instances'

package/server/migrations/1786100000000-PromoteEventActionAndSyncWarnings.ts

@@ -5,17 +5,17 @@ import { MigrationInterface, QueryRunner, TableColumn, TableIndex } from 'typeor
  *
  * ① `twin_events.action` — EPCIS 행위(ADD/OBSERVE/DELETE) 승격.
  *    되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다. 그래서 「이 트윈이 반출을 한 번이라도
- *    접었는가」가 진짜 delta 피드의 증거인데, 값이 `payload`(simple-json = TEXT) 안에 있는 동안에는
+ *    계산했는가」가 진짜 delta 피드의 증거인데, 값이 `payload`(simple-json = TEXT) 안에 있는 동안에는
  *    5개 드라이버 어디에서도 그 질문을 할 수 없었다(DB별 JSON 연산자 금지).
  *
  * ② `twin_references.last_warning_count` — 마지막 동기에서 못 옮긴 값의 수.
- *    세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 조용히 성공한다.
+ *    세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 성공이라 답하면서 아무 일도 하지 않는다.
  *
  * **둘 다 nullable, 기본값 없음.** 기본값 0 을 깔면 「없었다」와 「세지 않았다」가 같아지고, 그
  * 구분이 단계 판정의 전부다(옛 행은 모르는 것이 맞다 — 채워 넣지 않는다).
  *
  * 인덱스 `ix_twin_event_6` 는 저널이 큰 환경에서 생성에 시간이 걸린다. 그래도 만드는 이유:
- * 없으면 「반출을 접었나」가 그 인스턴스 저널 전량 주사가 되고, 반출이 **없는** 경우(초기 상태이자
+ * 없으면 「반출을 계산했나」가 그 인스턴스 저널 전량 주사가 되고, 반출이 **없는** 경우(초기 상태이자
  * 가장 흔한 경우)가 항상 최악이다.
  *
  * 멱등: 이미 있으면 아무것도 하지 않는다. TypeORM API 만 쓴다(raw SQL 금지 — 드라이버 5종).

package/server/migrations/1786200000000-CarryLiveFeedCursor.ts

@@ -3,7 +3,7 @@ import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm'
 /**
  * `twin_references.live_cursor` — **어디까지 읽었나**를 재기동 너머로 잇는다.
  *
- * ── 무엇이 조용히 사라지고 있었나 (2026-08-23 실측) ─────────────────────────
+ * ── 무엇이 오류 없이 사라지고 있었나 (2026-08-23 실측) ─────────────────────────
  * 라이브 어댑터가 붙을 때마다 `Date.now() − 되돌아볼 날수` 로 창을 새로 만들었다. 그래서 **재기동마다
  * 미러의 과거가 잘렸다** — 작업 2,855 → 2,820(그 사이 8시간이 흐른 만큼). 미러가 아는 것이 「원본의
  * 사실」이 아니라 「창의 함수」였고, 화면은 그 수를 보이면서 그 사실을 말하지 않았다.
@@ -15,7 +15,7 @@ import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm'
  * 재기동 연속성으로 이어받는다. 「우리가 어디까지 읽었나」가 정확히 그 성질이다.
  *
  * 그리고 스냅샷 체크포인트와 성질이 다르다: 그쪽은 잃어도 원천이 정정해 준다(그래서 TTL 캐시로 족하다).
- * **이 값은 잃으면 원천에 묻지 않게 된다** — 창이 다시 미끄러지고, 그 손실은 오류 없이 조용하다.
+ * **이 값은 잃으면 원천에 묻지 않게 된다** — 창이 다시 미끄러지고, 그 손실은 오류 없이 들어온 것이 없다.
  * 만료되는 자리에 둘 수 없다.
  *
  * ── 모양 ────────────────────────────────────────────────────────────────────

package/server/migrations/1786300000000-IndexEventTypeByTime.ts

@@ -0,0 +1,48 @@
+import { MigrationInterface, QueryRunner, TableIndex } from 'typeorm'
+
+/**
+ * 「이 종류의 사실을 시각순으로」 — 그 축에 인덱스가 없었다.
+ *
+ * ── 무엇이 났나 (2026-08-25 실측 · 승화푸드) ─────────────────────────────────
+ * 지난 기록 조회는 필터가 없을 때 `revision DESC`(적힌 순서)로 잘랐다. 연결된 시스템을 되읽는
+ * 트윈에서는 그 순서가 일어난 순서와 달라서, 공정 타임라인이 4월 사실을 최근 것으로 그렸다. 그래서
+ * 기본을 시각순으로 고쳤는데(`journal-order.ts`), 그때 이 인덱스가 없는 것이 드러났다.
+ *
+ *   ix_2 (domain, instance, eventType, revision)   종류는 걸러지고 정렬이 적힌 순서다
+ *   ix_1 (domain, instance, eventTime)             정렬은 맞고 종류를 못 거른다
+ *
+ * 종류로 거르고 시각으로 정렬하면 `ix_1` 로 걷다가 행마다 테이블을 열어 종류를 확인한다. 찾는 종류가
+ * 며칠 전에 멈춘 트윈에서는 그 사이 행을 전부 읽고 버린다. 실측: 200건에 1.7초(같은 조회가 옛 정렬로는
+ * 0.001초). 승화푸드에서 작업 사실은 8월 22일에 멈춰 있고 그 뒤로 리비전이 110만 늘었다.
+ *
+ * ── 그 1.7초가 서버 전체를 막았다 ───────────────────────────────────────────
+ * 공정 타임라인은 5초마다 세 종류를 부른다. sqlite 드라이버는 연결이 하나라서, 5초 주기에 5초가 넘는
+ * 일감이 들어오면 나머지 질의가 전부 뒤에 선다. 39분 동안 느린 질의 3,152건이 쌓였고, 한 줄짜리
+ * `domains` 조회가 중간 7.4초로 찍혔다 — 그 질의의 문제가 아니라 줄을 선 값이다.
+ *
+ * ── 왜 이제 얹나 ────────────────────────────────────────────────────────────
+ * 엔티티 주석이 「저널 하나가 아주 커져서 이 축들의 조회가 느려지면 그때 측정을 근거로 인덱스를 추가할
+ * 일이지, 지레 얹어 쓰기를 무겁게 할 일은 아니다」라고 적어 두었다. 그 측정이 나왔다.
+ *
+ * 큰 기록에서는 생성에 시간이 걸린다(47GB 개발 파일에서 수분). 멱등이므로 다시 돌려도 안전하고,
+ * TypeORM API 만 쓴다(드라이버 다섯을 다 지나가야 하므로 raw SQL 금지).
+ */
+const EVENTS = 'twin_events'
+const IX = 'ix_twin_event_7'
+const COLUMNS = ['domain_id', 'instance_id', 'event_type', 'event_time']
+
+export class IndexEventTypeByTime1786300000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const events = await queryRunner.getTable(EVENTS)
+    if (!events) return
+    if (events.indices.some(i => i.name === IX)) return
+    await queryRunner.createIndex(events, new TableIndex({ name: IX, columnNames: COLUMNS }))
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const events = await queryRunner.getTable(EVENTS)
+    if (!events) return
+    if (!events.indices.some(i => i.name === IX)) return
+    await queryRunner.dropIndex(events, IX)
+  }
+}

package/server/migrations/1786400000000-IndexEventCreatedAt.ts

@@ -0,0 +1,38 @@
+import { MigrationInterface, QueryRunner, TableIndex } from 'typeorm'
+
+/**
+ * 「이 트윈의 오래된 기록」 — 보관 기간 정리가 쓰는 축에 인덱스가 없었다.
+ *
+ * ── 무엇이 났나 (2026-08-27 실측 · 개발 파일 51GB · 3,128만 행) ───────────────
+ * 정리는 `created_at` 으로 자른다(보관은 저장 나이의 문제이고 저장 나이는 실제 시계다). 그런데 그 축에
+ * 인덱스가 없어서, 매 배치마다 그 트윈의 저널을 전량 주사했다.
+ *
+ *   hatio-mx2 의 7일 밖 행을 세기       208초   ← 1,029만 행을 전부 읽는다(7일 밖은 2,446건뿐이다)
+ *   revision 으로 한 행 짚기            0.004초
+ *
+ * 정리는 한 창에 2초만 쓰도록 예산이 걸려 있다. 그 2초를 주사에 다 쓰고 44건만 지우고 멈췄다. 지금은
+ * 지울 것이 적어서 크게 드러나지 않지만, 보관 기간을 줄이거나 쓰는 양이 늘면 따라가지 못한다.
+ *
+ * ── 큰 기록에서는 만드는 데 시간이 걸린다 ───────────────────────────────────
+ * 3,128만 행에 인덱스를 만드는 동안 쓰기가 막힌다(sqlite 는 쓰기가 하나다). 서버를 내린 뒤 돌린다.
+ * 멱등이므로 다시 돌려도 안전하고, TypeORM API 만 쓴다(드라이버 다섯을 다 지나가야 하므로 raw SQL 금지).
+ */
+const EVENTS = 'twin_events'
+const IX = 'ix_twin_event_8'
+const COLUMNS = ['domain_id', 'instance_id', 'created_at']
+
+export class IndexEventCreatedAt1786400000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const events = await queryRunner.getTable(EVENTS)
+    if (!events) return
+    if (events.indices.some(i => i.name === IX)) return
+    await queryRunner.createIndex(events, new TableIndex({ name: IX, columnNames: COLUMNS }))
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const events = await queryRunner.getTable(EVENTS)
+    if (!events) return
+    if (!events.indices.some(i => i.name === IX)) return
+    await queryRunner.dropIndex(events, IX)
+  }
+}

package/server/migrations/1786500000000-CreateTwinSubjectEvents.ts

@@ -0,0 +1,93 @@
+import { MigrationInterface, QueryRunner, Table, TableIndex } from 'typeorm'
+
+/**
+ * **대상별 사건 목록** — 조회용 파생 표를 만든다.
+ *
+ * ── 왜 (2026-08-27 실측) ────────────────────────────────────────────────────
+ * 360 화면이 「이 대상의 이력」을 묻고 그 조회가 64초다. 「무엇으로 걸러 시각순으로 정렬해 앞에서
+ * 30개」라는 모양에 맞는 목차가 저널에 없고, 얹어도 풀리지 않는다.
+ *
+ *   여러 값으로 거르면(IN) 정렬 때문에 목차를 못 쓴다
+ *   축이 늘 때마다 저널의 목차가 늘어난다 — 360 의 축 넷이면 13개가 된다
+ *   품목과 로트가 한 문자열에 붙어 있어 품목만으로는 찾을 수 없다
+ *
+ * ── 비어서 시작한다 ────────────────────────────────────────────────────────
+ * 이 표는 **앞으로만 채운다.** 기존 3,128만 건을 소급해서 채우지 않는다 — 그래야 새 조회 축이 필요할
+ * 때마다 전체를 다시 만드는 구조가 되지 않는다. 담지 않은 구간은 조회가 `coveredFrom` 으로 말한다.
+ *
+ * 그래서 이 마이그레이션은 큰 기록에서도 값싸다(표와 목차를 만들 뿐, 채우지 않는다).
+ *
+ * 멱등이고 TypeORM API 만 쓴다(드라이버 다섯을 다 지나가야 하므로 raw SQL 금지). 컬럼 타입 이름을
+ * 적지 않는 규율은 엔티티와 같다 — `datetime` 은 Postgres 가 거절한다.
+ *
+ * 설계: `operato-twin/design/plans/read-models.md`
+ */
+const TABLE = 'twin_subject_events'
+
+export class CreateTwinSubjectEvents1786500000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    /*
+     * 표마다 따로 본다 — 하나가 이미 있다고 여기서 돌아가면 나머지가 만들어지지 않는다. 실제로 그렇게
+     * 적어 두었다가, 사건 목록만 있고 진행 지점 표가 없는 상태를 만들었다.
+     */
+    if (!(await queryRunner.hasTable(TABLE))) {
+      await this.createSubjectEvents(queryRunner)
+    }
+  }
+
+  private async createSubjectEvents(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.createTable(
+      new Table({
+        name: TABLE,
+        columns: [
+          { name: 'id', type: 'varchar', length: '36', isPrimary: true },
+          { name: 'domain_id', type: 'varchar', length: '36', isNullable: true },
+          { name: 'instance_id', type: 'varchar', isNullable: false },
+          { name: 'subject_kind', type: 'varchar', isNullable: false },
+          { name: 'subject_id', type: 'varchar', isNullable: false },
+          /* 시각 컬럼의 타입 이름은 드라이버가 정한다 — `timestamp` 는 sqlite 가 모르고 `datetime` 은 Postgres 가 거절한다. */
+          { name: 'event_time', type: queryRunner.connection.driver.mappedDataTypes.createDate as string, isNullable: false },
+          { name: 'revision', type: 'int', isNullable: false },
+          { name: 'event_type', type: 'varchar', isNullable: false },
+          { name: 'event_id', type: 'varchar', length: '36', isNullable: true },
+          {
+            name: 'created_at',
+            type: queryRunner.connection.driver.mappedDataTypes.createDate as string,
+            isNullable: true
+          }
+        ]
+      }),
+      true
+    )
+
+    const table = await queryRunner.getTable(TABLE)
+    if (!table) return
+
+    /* 이 표의 존재 이유 — 「이 대상의 것을 최신순으로」가 목차를 위에서 읽고 끝난다(정렬 없음). */
+    if (!table.indices.some(i => i.name === 'ix_twin_subject_event_0')) {
+      await queryRunner.createIndex(
+        table,
+        new TableIndex({
+          name: 'ix_twin_subject_event_0',
+          columnNames: ['domain_id', 'instance_id', 'subject_kind', 'subject_id', 'event_time']
+        })
+      )
+    }
+    /* 보관 상한을 지우는 축 — 「이 트윈에서 오래된 줄」. */
+    if (!table.indices.some(i => i.name === 'ix_twin_subject_event_1')) {
+      await queryRunner.createIndex(
+        table,
+        new TableIndex({
+          name: 'ix_twin_subject_event_1',
+          columnNames: ['domain_id', 'instance_id', 'event_time']
+        })
+      )
+    }
+
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    if (!(await queryRunner.hasTable(TABLE))) return
+    await queryRunner.dropTable(TABLE)
+  }
+}

package/server/migrations/index.ts

@@ -5,9 +5,15 @@
 import { RenameTwinInstanceBoardToModel1786000000000 } from './1786000000000-RenameTwinInstanceBoardToModel.js'
 import { PromoteEventActionAndSyncWarnings1786100000000 } from './1786100000000-PromoteEventActionAndSyncWarnings.js'
 import { CarryLiveFeedCursor1786200000000 } from './1786200000000-CarryLiveFeedCursor.js'
+import { IndexEventTypeByTime1786300000000 } from './1786300000000-IndexEventTypeByTime.js'
+import { IndexEventCreatedAt1786400000000 } from './1786400000000-IndexEventCreatedAt.js'
+import { CreateTwinSubjectEvents1786500000000 } from './1786500000000-CreateTwinSubjectEvents.js'
 
 export const migrations = [
   RenameTwinInstanceBoardToModel1786000000000,
   PromoteEventActionAndSyncWarnings1786100000000,
-  CarryLiveFeedCursor1786200000000
+  CarryLiveFeedCursor1786200000000,
+  IndexEventTypeByTime1786300000000,
+  IndexEventCreatedAt1786400000000,
+  CreateTwinSubjectEvents1786500000000
 ]

package/server/routes.ts

@@ -1,5 +1,73 @@
-/* 헤드리스 트윈은 GraphQL(subscription/mutation)로 동작 — REST 라우터는 미사용(빈 부트스트랩). */
-process.on('bootstrap-module-global-public-route' as any, (app, globalPublicRouter) => {})
-process.on('bootstrap-module-global-private-route' as any, (app, globalPrivateRouter) => {})
-process.on('bootstrap-module-domain-public-route' as any, (app, domainPublicRouter) => {})
-process.on('bootstrap-module-domain-private-route' as any, (app, domainPrivateRouter) => {})
+/*
+ * 이 패키지가 여는 HTTP 자리 — 지금은 웹훅 하나다.
+ *
+ * ── 왜 여기인가 ─────────────────────────────────────────────────────────────
+ * 커넥터는 주소를 만들 수 없다. 어댑터 계약에 주소를 등록하는 자리가 없고, 있어서도 안 된다 — 주소는
+ * 앱의 것이고 커넥터마다 제각기 열면 인증도 제각기가 된다.
+ *
+ * 그래서 입구는 **하나**다. 어느 연결의 것인지는 주소의 이름으로 가려내고, 본문을 우리 어휘로 옮기는
+ * 것은 그 연결의 커넥터가 한다(§`reference-hook`).
+ *
+ * ── 왜 도메인 공개 라우터인가 ───────────────────────────────────────────────
+ * 밀어 주는 쪽은 사람이 아니다. 사람 인증(JWT)을 요구하면 연결된 시스템이 우리 토큰을 발급받아
+ * 갱신하며 관리해야 하고, 대부분의 현장에서 그것 때문에 연동이 서지 않는다.
+ *
+ * 대신 **연결마다 비밀값**을 두고 그것으로 확인한다. 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 —
+ * 인증 없는 입구를 열어 두는 것보다 훅을 못 쓰는 것이 낫다.
+ */
+import { ingestCanonicalRecords } from './engine/canonical-ingest.js'
+import { TwinEngine } from './engine/twin-engine.js'
+import { handleHook } from './service/reference/reference-hook.js'
+
+process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: any) => {
+  /*
+   * 주소에 트윈까지 적는다 — 어느 트윈에 넣을지 짐작하지 않는다.
+   *
+   * 한 연결이 여러 사이트를 만들면 트윈도 여럿이다. 본문을 보고 고르게 하면 그 판단이 커넥터마다
+   * 달라지고, 틀리면 다른 공장의 사실이 이 공장에 들어간다. 주소가 말하게 하면 그 일이 없다.
+   */
+  router.post('/twin/hook/:source/:instanceId', async (ctx: any) => {
+    const domain = ctx.state?.domain
+    if (!domain) {
+      ctx.status = 400
+      ctx.body = { ok: false, error: 'no domain context' }
+      return
+    }
+    const outcome = await handleHook({
+      domainId: domain.id,
+      source: String(ctx.params.source ?? ''),
+      instanceId: String(ctx.params.instanceId ?? ''),
+      headers: (ctx.request?.headers ?? {}) as Record<string, unknown>,
+      body: ctx.request?.body,
+      /*
+       * 폴링이 쓰는 길을 그대로 쓴다 — 검증도 유입도 같은 자리다. 그래서 트윈 쪽에서는 물어서 받은
+       * 것과 밀어 받은 것이 구별되지 않는다. 구별되는 것은 유입 장부의 `sources` 한 줄뿐이다.
+       */
+      ingest: (instanceId, records) => {
+        const { accepted, rejected, masterData } = ingestCanonicalRecords(
+          records as any,
+          domain.id,
+          new Date().toISOString(),
+          TwinEngine.factScope(domain.id, instanceId)
+        )
+        /* 사건이 아닌 것은 상태만 세운다 — 밀어 받는 길도 같은 규율이다(§`applyMasterData`). */
+        if (masterData.length) TwinEngine.applyMasterData(domain.id, instanceId, masterData)
+        const { applied, duplicates } = TwinEngine.ingestLiveResult(domain.id, instanceId, accepted, 'hook')
+        /*
+         * 커널이 받지 못한 수를 이름으로 남긴다 — 트윈이 멈춘 사이 버려진 레코드를 「통과」로 세면
+         * 화면이 100% 라고 말한다. 중복으로 걸러진 것은 버려진 것이 아니므로 빼고 센다.
+         */
+        const undelivered = Math.max(0, accepted.length - applied - duplicates)
+        TwinEngine.recordIngestResult(domain.id, instanceId, records.length, rejected, Date.now(), undelivered)
+        return { applied, duplicates, rejected: rejected.length }
+      }
+    })
+    ctx.status = outcome.status
+    ctx.body = outcome.body
+  })
+})
+
+/* 나머지 셋은 이 패키지가 쓰지 않는다 — 자리는 남겨 둔다(다른 모듈이 같은 신호를 기다린다). */
+process.on('bootstrap-module-global-public-route' as any, (_app: any, _router: any) => {})
+process.on('bootstrap-module-global-private-route' as any, (_app: any, _router: any) => {})
+process.on('bootstrap-module-domain-private-route' as any, (_app: any, _router: any) => {})

package/server/service/index.ts

@@ -24,6 +24,7 @@ export * from './twin-lifecycle/domain-catalog.js'
 
 /* IMPORT ENTITIES AND RESOLVERS */
 import { entities as TwinEventEntities } from './twin-event/index.js'
+import { entities as TwinSubjectEntities, resolvers as TwinSubjectResolvers } from './twin-subject/index.js'
 import { entities as TwinAuditEntities, resolvers as TwinAuditResolvers } from './twin-audit/index.js'
 import { entities as TwinInstanceEntities } from './twin-instance/index.js'
 import { entities as TwinStructureEntities } from './twin-structure/index.js'
@@ -41,10 +42,13 @@ import { resolvers as TwinForecastResolvers } from './twin-forecast/index.js'
 import { resolvers as TwinAttentionResolvers } from './twin-attention/index.js'
 import { resolvers as TwinMetricsResolvers } from './twin-metrics/index.js'
 import { resolvers as TwinReadinessResolvers } from './twin-readiness/index.js'
+/* 지난 기록 채우기 — 저널에만 쓰는 문. 라이브 유입과 판단이 달라 문을 따로 둔다. */
+import { resolvers as TwinBackfillResolvers } from './twin-backfill/index.js'
 
 export const entities = [
   /* ENTITIES */
   ...TwinEventEntities,
+  ...TwinSubjectEntities,
   ...TwinIngestWindowEntities,
   ...TwinAuditEntities,
   ...TwinInstanceEntities,
@@ -71,11 +75,13 @@ export const schema = {
     ...TwinAttentionResolvers,
     ...TwinMetricsResolvers,
     ...TwinReadinessResolvers,
+    ...TwinBackfillResolvers,
     ...TwinIngestWindowResolvers,
     ...TwinModelResolvers,
     ...TwinSpaceResolvers,
     ...TwinTargetResolvers,
-    ...TwinReferenceResolvers
+    ...TwinReferenceResolvers,
+    ...TwinSubjectResolvers
   ],
   directives: {}
 }

package/server/service/reference/control-routing.ts

@@ -22,7 +22,7 @@ import { capabilitiesOf, getAdapter, type ControlCommand, type ControlResult, ty
 /**
  * 이 트윈의 원본에 구동 명령을 보낸다 — **원본이 없거나 능력을 선언하지 않으면 거절한다.**
  *
- * 거절을 조용히 하지 않는다: 사유 코드를 돌려주고 화면이 그것을 사람 말로 옮긴다. 「아무 일도 일어나지
+ * 거절을 알리지 않고 하지 않는다: 사유 코드를 돌려주고 화면이 그것을 사람 말로 옮긴다. 「아무 일도 일어나지
  * 않았다」가 가장 비싼 답이다.
  */
 export async function routeControl(domainId: string, instanceId: string, command: ControlCommand): Promise<ControlResult> {

package/server/service/reference/discovery-result.ts

@@ -3,7 +3,7 @@
  *
  * ── 왜 있나 (2026-08-06) ────────────────────────────────────────────────────
  * 실 시스템을 연결해 "거기 있는 것" 으로 트윈을 만드는 경로에서, 발견이 실패하면 화면이
- * **"사이트를 찾지 못했습니다"** 라고만 말했다. 네 가지가 그 한 문장으로 접혀 있었다.
+ * **"사이트를 찾지 못했습니다"** 라고만 말했다. 네 가지가 그 한 문장에 섞여 있었다.
  *
  *  ① 그 레퍼런스가 등록돼 있지 않다        (`!ref → []`)
  *  ② 어댑터 종류를 모른다                  (`!adapter → []`)
@@ -71,7 +71,7 @@ export const discoveryTimedOut = (source: string, seconds: number): DiscoveryErr
 })
 
 /**
- * 어댑터가 준 것을 결과로 접는다.
+ * 어댑터가 준 것을 결과로 처리한다.
  *
  * **사이트가 없는 것을 실패로 만들지 않는다** — 연결이 되고 조회가 성공했는데 공장이 하나도 없는
  * 시스템은 있을 수 있다(권한이 좁거나 아직 등록되지 않은 경우). 그것은 사실이고, 화면은 "없다" 고
@@ -81,7 +81,7 @@ export function discovered<S>(sites: readonly S[] | undefined | null): Discovery
   return { sites: Array.isArray(sites) ? [...sites] : [] }
 }
 
-/** 실패를 결과로 접는다 — 사이트는 비어 있다(반쪽 목록을 성공처럼 보이게 하지 않는다). */
+/** 실패를 결과로 처리한다 — 사이트는 비어 있다(반쪽 목록을 성공처럼 보이게 하지 않는다). */
 export function failed<S>(error: DiscoveryError): DiscoveryResult<S> {
   return { sites: [], error }
 }

package/server/service/reference/hook-contract.ts

@@ -0,0 +1,103 @@
+/*
+ * 웹훅의 규약 — 상태 코드 · 비밀값 · 어느 트윈인가.
+ *
+ * 데이터베이스를 부르는 부분과 갈라 둔다(§`reference-hook`): 규약만 있는 자리라야 시험이 엔티티를
+ * 끌고 오지 않는다. 실제로 그것 때문에 시험이 서지 않았다.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 지금 모든 커넥터가 주기적으로 물어봅니다(폴링). 그 방식은 두 가지를 치릅니다. 연결된 시스템이 값을
+ * 갱신하는 주기보다 자주 물으면 같은 값을 되풀이 받고, 그쪽 서버에 그만큼 부담을 줍니다. 실제로
+ * 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을 받아 왔습니다.
+ *
+ * 연결된 시스템이 「바뀌었다」를 말해 줄 수 있으면 그것을 받는 것이 낫습니다. 이 파일이 그 입구입니다.
+ *
+ * ── 규약 ────────────────────────────────────────────────────────────────────
+ *
+ *   주소     POST /domain/<도메인>/twin/hook/<연결이름>/<트윈>
+ *   인증     연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다
+ *            X-Twin-Hook-Secret: <비밀값>   또는   Authorization: Bearer <비밀값>
+ *   본문     연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다
+ *   응답     아래 §`hookStatus`
+ *
+ * ── 왜 사람 인증(JWT)이 아닌가 ──────────────────────────────────────────────
+ * 밀어 주는 쪽은 사람이 아닙니다. 우리 토큰을 발급받아 갱신하며 관리하라고 요구하면 대부분의 현장에서
+ * 연동이 서지 않습니다. 그래서 연결마다 비밀값을 두고 그것으로 확인합니다.
+ *
+ * **비밀값이 없는 연결은 훅을 받지 않습니다.** 기본이 거부입니다 — 인증 없는 입구를 열어 두는 것보다
+ * 훅을 못 쓰는 것이 낫습니다.
+ *
+ * ── 왜 커넥터가 옮기나 (시나리오가 아니라) ──────────────────────────────────
+ * 연결된 시스템의 웹훅은 그쪽이 정한 고정된 모양으로 옵니다. 그 모양을 아는 것은 그 커넥터이고,
+ * 옮기는 판단은 코드여야 테스트로 지킬 수 있습니다. 실제로 지금 커넥터들이 코드로 판단합니다 —
+ * 통신이 끊긴 설비의 값은 보내지 않고, 잰 시각이 나아가지 않은 줄은 거릅니다. 그 판단을 변환식으로
+ * 옮기면 약해지고 테스트가 없어집니다.
+ *
+ * ── 밀어 주기만으로는 안 된다 ───────────────────────────────────────────────
+ * 훅은 반드시 놓칩니다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 그래서
+ * 훅을 쓰는 연결도 **드문 폴링을 유지합니다.** 폴링의 역할이 「값을 가져오는 것」에서 「놓친 것이 있나
+ * 확인하는 것」으로 바뀌는 것입니다. 그 주기는 연결 설정이 정합니다.
+ *
+ * ── 같은 것이 두 번 오는 것 ─────────────────────────────────────────────────
+ * 밀어 주는 방식은 재전송이 정상입니다(그쪽이 우리 응답을 못 받으면 다시 보냅니다). 그것은 유입
+ * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지
+ * 함께 알립니다.
+ */
+/** 훅 요청의 결과 — 상태 코드와 본문을 함께 정한다(부르는 쪽이 그대로 답한다). */
+export interface HookOutcome {
+  status: number
+  body: Record<string, unknown>
+}
+
+/**
+ * 응답 코드 규약 — **재시도로 해결되는 것과 그렇지 않은 것을 가른다.**
+ *
+ * 밀어 주는 쪽은 응답 코드로 재시도를 정합니다. 그래서 우리가 코드를 아무렇게나 주면 두 가지가
+ * 일어납니다: 고칠 수 없는 것을 영원히 다시 보내거나, 잠깐의 문제로 사라진 사실을 아무도 모릅니다.
+ *
+ *   200  받아서 반영했다
+ *   401  비밀값이 다르다                    재시도해도 같다
+ *   404  모르는 연결이거나 모르는 트윈       재시도해도 같다
+ *   400  본문을 우리 레코드로 옮길 수 없다   재시도해도 같다(그쪽 모양이 바뀐 것이다)
+ *   409  그 트윈이 지금 실시간으로 돌지 않는다  사람이 트윈을 띄워야 한다
+ *   501  그 커넥터가 훅을 받을 줄 모른다      코드가 없다
+ *   500  우리 쪽 오류                        재시도하면 될 수 있다
+ */
+export const HOOK_STATUS = {
+  ok: 200,
+  badSecret: 401,
+  unknownTarget: 404,
+  badPayload: 400,
+  notLive: 409,
+  unsupported: 501,
+  failed: 500
+} as const
+
+/** 헤더에서 비밀값을 꺼낸다 — 두 가지 방식을 받는다(밀어 주는 쪽의 관습이 갈린다). */
+export function secretFromHeaders(headers: Record<string, unknown> | undefined): string {
+  const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()
+  const direct = pick('x-twin-hook-secret')
+  if (direct) return direct
+  const auth = pick('authorization')
+  return auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : ''
+}
+
+/**
+ * 비밀값 비교 — **길이가 다르면 바로 거절하고, 같으면 끝까지 비교한다.**
+ *
+ * 앞에서 다른 것을 발견하고 곧바로 답하면 응답 시간이 달라지고, 그 차이로 비밀값을 한 글자씩 알아낼 수
+ * 있습니다. 그래서 같은 길이면 전부를 비교합니다.
+ */
+export function secretMatches(given: string, expected: string): boolean {
+  if (!expected || !given || given.length !== expected.length) return false
+  let diff = 0
+  for (let i = 0; i < expected.length; i++) diff |= given.charCodeAt(i) ^ expected.charCodeAt(i)
+  return diff === 0
+}
+
+/** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */
+export function producedInstance(ref: { scopeSpec?: any } | null | undefined, instanceId: string): { siteId: string } | undefined {
+  const produced: any[] = (ref?.scopeSpec as any)?.produced ?? []
+  const hit = produced.find(p => String(p?.instanceId ?? '') === instanceId)
+  return hit?.siteId ? { siteId: String(hit.siteId) } : undefined
+}
+

package/server/service/reference/ingest-space.ts

@@ -9,14 +9,14 @@
  * `<source>-site` 로 파생돼, 새 트윈은 늘 새 현장처럼 생겼다. 데이터로는 가능한 일이 저작으로는
  * 불가능했다.
  *
- * ── 없는 공간에 조용히 새 공간을 만들지 않는다 ────────────────────────────────
+ * ── 없는 공간에 알리지 않고 새 공간을 만들지 않는다 ────────────────────────────────
  * "이 현장에 더한다" 는 요청이 오타·낡은 목록으로 빗나갔을 때 새 공간을 만들어 주면, 사용자는
  * 합쳤다고 믿고 화면에서는 따로 놀게 된다 — 나중에 두 현장을 손으로 합쳐야 하고, 그때는 이미
  * 이벤트가 양쪽에 쌓여 있다. 그래서 **모르는 공간이면 거절한다.**
  *
- * ── 같은 id 를 쓰는 구역은 조용히 합쳐지므로 알린다 ──────────────────────────
+ * ── 같은 id 를 쓰는 구역은 알리지 않고 합쳐지므로 알린다 ──────────────────────────
  * 공간 content 의 구역·랜드마크는 id 로 합집합을 만든다(`unionById`). 두 렌즈가 우연히 같은 구역
- * id(`a-yard` 따위)를 쓰면 서로 다른 구역이 하나로 접힌다. 막을 일은 아니다(같은 현장의 같은 구역을
+ * id(`a-yard` 따위)를 쓰면 서로 다른 구역이 하나로 합쳐진다. 막을 일은 아니다(같은 현장의 같은 구역을
  * 가리키는 정당한 경우가 많다) — 다만 **모르고 지나가지 않게** 경고로 돌려준다.
  */
 
@@ -37,7 +37,7 @@ export const INGEST_SPACE_NOT_FOUND = 'space-not-found'
  * @param masterSpaceId 마스터에서 파생된 공간 id(요청이 없을 때의 기본).
  * @param requested     사용자가 고른 기존 공간 id. 없으면 빈 값/undefined.
  * @param requestedExists 그 공간이 이 테넌트에 실제로 있나(호출측이 조회해 넘긴다).
- * @throws 요청한 공간이 없으면 — 조용히 새로 만들지 않는다.
+ * @throws 요청한 공간이 없으면 — 알리지 않고 새로 만들지 않는다.
  */
 export function resolveIngestSpace(masterSpaceId: string, requested: string | undefined | null, requestedExists: boolean): IngestSpaceChoice {
   const want = (requested ?? '').trim()