@things-factory/headless-twin 10.0.11 → 10.0.13

package/dist-shared/touched-items.js

@@ -0,0 +1,80 @@
+"use strict";
+/*
+ * 한 사건이 **어느 물품을 건드렸나** — 브로드캐스팅이 바뀐 것만 만들 수 있게. 순수(import 없음).
+ *
+ * ── 왜 물품만인가 (2026-08-21 실측) ─────────────────────────────────────────
+ * 브로드캐스팅 한 번이 만드는 payload 는 엔티티 수만큼이고, 그 대부분이 물품이다(실측: 엔티티 3,611 중
+ * 물품 2,400). 자리·설비·인원·자산은 모델이 정한 수라 적고(자리 최대 200, 평균 19), 작업·오더는 수백이다.
+ * 그래서 **물품 축만 걸러도** 만드는 양의 3분의 2가 사라진다.
+ *
+ * 나머지 축은 **매번 전부 만든다.** 걸러서 얻는 것이 적고, 잘못 걸러서 잃는 것이 크기 때문이다 —
+ * 예를 들어 물품이 한 자리에서 다른 자리로 가면 **두 자리의 점유가 함께 바뀌는데** EPCIS 사건은 읽은
+ * 지점 하나만 말한다. 그것으로 자리를 걸렀으면 떠난 자리의 점유가 낡은 값으로 남는다(오류 없이).
+ *
+ * ── 모르면 전부다 ───────────────────────────────────────────────────────────
+ * 이 함수가 `null` 을 돌려주면 「이 사건이 어느 물품을 건드렸는지 말할 수 없다」는 뜻이고, 그때 호출자는
+ * **전부 다시 만든다**(지금까지의 거동). 낯선 어휘가 오면 조용히 빠뜨리는 것이 아니라 비싸게 안전한
+ * 쪽으로 떨어진다 — 화면이 낡는 것보다 계산을 한 번 더 하는 것이 낫다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.touchedItemKeys = touchedItemKeys;
+/** 물품 태그는 개체 식별자(epc)다 — 자리·설비와 달리 id 가 아니다(entity-delta 와 같은 규약). */
+function push(out, v) {
+    if (typeof v === 'string' && v)
+        out.add(v);
+}
+/**
+ * 물품을 건드리지 않는다고 **선언된** 사건들 — 커널의 운영 델타와 에너지 사건.
+ *
+ * 이 목록은 커널 계약(`OP_EVENT`·`ENERGY_EVENT`)에서 왔다. 여기 없는 낱말이 오면 「모른다」로 떨어져
+ * 전부 다시 만든다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리는 대신 비싸게 안전한 쪽을 고른다.
+ *
+ * 근거: 미러의 리듀서에서 이 사건들은 작업·설비·인원·자산·오더·계량만 바꾼다(물품 축을 만지지 않는다).
+ * 자리 점유는 이 사건들도 바꾸지만, 자리는 **어차피 매번 전부 다시 만든다**(위 주석).
+ */
+const ITEM_FREE_EVENTS = new Set([
+    'task.status',
+    'equipment.status',
+    'person.status',
+    'asset.status',
+    'order.status',
+    'quality.output',
+    'attention.acked'
+]);
+/**
+ * 이 사건이 건드린 물품 태그들. **말할 수 없으면 `null`** — 호출자는 그때 전부 다시 만든다.
+ *
+ * 개체를 말하는 자리를 전부 본다: `epcList`(관측·커미셔닝) · `parentID`(집약의 부모) ·
+ * `childEPCs`(집약의 자식) · `inputEPCList`·`outputEPCList`(변환의 입출력).
+ */
+function touchedItemKeys(envelope) {
+    const type = envelope?.eventType;
+    if (typeof type !== 'string')
+        return null;
+    const d = envelope?.data ?? envelope;
+    if (!d || typeof d !== 'object')
+        return null;
+    if (type.startsWith('energy.') || ITEM_FREE_EVENTS.has(type))
+        return new Set();
+    /* EPCIS 밖의 낯선 낱말 — 무엇을 바꿨는지 우리가 모른다. */
+    if (!type.startsWith('epcis.'))
+        return null;
+    const out = new Set();
+    for (const v of d.epcList ?? [])
+        push(out, v);
+    for (const v of d.childEPCs ?? [])
+        push(out, v);
+    for (const v of d.inputEPCList ?? [])
+        push(out, v);
+    for (const v of d.outputEPCList ?? [])
+        push(out, v);
+    push(out, d.parentID);
+    /*
+     * 개체를 하나도 말하지 않은 EPCIS 사건은 **부류 수량**으로 말한 것이다(`quantityList`). 그 부류의
+     * 물품이 어느 것인지는 여기서 알 수 없으므로 전부 다시 만든다.
+     */
+    if (!out.size)
+        return null;
+    return out;
+}
+//# sourceMappingURL=touched-items.js.map

package/dist-shared/touched-items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"touched-items.js","sourceRoot":"","sources":["../shared/touched-items.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;AAgCH,0CAwBC;AAtDD,sEAAsE;AACtE,SAAS,IAAI,CAAC,GAAgB,EAAE,CAAU;IACxC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,aAAa;IACb,kBAAkB;IAClB,eAAe;IACf,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,iBAAiB;CAClB,CAAC,CAAA;AAEF;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,QAAa;IAC3C,MAAM,IAAI,GAAG,QAAQ,EAAE,SAAS,CAAA;IAChC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACzC,MAAM,CAAC,GAAG,QAAQ,EAAE,IAAI,IAAI,QAAQ,CAAA;IACpC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAE5C,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAA;IAC9E,wCAAwC;IACxC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAA;IAE3C,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;IAC7B,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;IAC7C,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;IAC/C,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,YAAY,IAAI,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;IAClD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,aAAa,IAAI,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;IACnD,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAA;IAErB;;;OAGG;IACH,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IAE1B,OAAO,GAAG,CAAA;AACZ,CAAC","sourcesContent":["/*\n * 한 사건이 **어느 물품을 건드렸나** — 브로드캐스팅이 바뀐 것만 만들 수 있게. 순수(import 없음).\n *\n * ── 왜 물품만인가 (2026-08-21 실측) ─────────────────────────────────────────\n * 브로드캐스팅 한 번이 만드는 payload 는 엔티티 수만큼이고, 그 대부분이 물품이다(실측: 엔티티 3,611 중\n * 물품 2,400). 자리·설비·인원·자산은 모델이 정한 수라 적고(자리 최대 200, 평균 19), 작업·오더는 수백이다.\n * 그래서 **물품 축만 걸러도** 만드는 양의 3분의 2가 사라진다.\n *\n * 나머지 축은 **매번 전부 만든다.** 걸러서 얻는 것이 적고, 잘못 걸러서 잃는 것이 크기 때문이다 —\n * 예를 들어 물품이 한 자리에서 다른 자리로 가면 **두 자리의 점유가 함께 바뀌는데** EPCIS 사건은 읽은\n * 지점 하나만 말한다. 그것으로 자리를 걸렀으면 떠난 자리의 점유가 낡은 값으로 남는다(오류 없이).\n *\n * ── 모르면 전부다 ───────────────────────────────────────────────────────────\n * 이 함수가 `null` 을 돌려주면 「이 사건이 어느 물품을 건드렸는지 말할 수 없다」는 뜻이고, 그때 호출자는\n * **전부 다시 만든다**(지금까지의 거동). 낯선 어휘가 오면 조용히 빠뜨리는 것이 아니라 비싸게 안전한\n * 쪽으로 떨어진다 — 화면이 낡는 것보다 계산을 한 번 더 하는 것이 낫다.\n */\n\n/** 물품 태그는 개체 식별자(epc)다 — 자리·설비와 달리 id 가 아니다(entity-delta 와 같은 규약). */\nfunction push(out: Set<string>, v: unknown): void {\n  if (typeof v === 'string' && v) out.add(v)\n}\n\n/**\n * 물품을 건드리지 않는다고 **선언된** 사건들 — 커널의 운영 델타와 에너지 사건.\n *\n * 이 목록은 커널 계약(`OP_EVENT`·`ENERGY_EVENT`)에서 왔다. 여기 없는 낱말이 오면 「모른다」로 떨어져\n * 전부 다시 만든다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리는 대신 비싸게 안전한 쪽을 고른다.\n *\n * 근거: 미러의 리듀서에서 이 사건들은 작업·설비·인원·자산·오더·계량만 바꾼다(물품 축을 만지지 않는다).\n * 자리 점유는 이 사건들도 바꾸지만, 자리는 **어차피 매번 전부 다시 만든다**(위 주석).\n */\nconst ITEM_FREE_EVENTS = new Set([\n  'task.status',\n  'equipment.status',\n  'person.status',\n  'asset.status',\n  'order.status',\n  'quality.output',\n  'attention.acked'\n])\n\n/**\n * 이 사건이 건드린 물품 태그들. **말할 수 없으면 `null`** — 호출자는 그때 전부 다시 만든다.\n *\n * 개체를 말하는 자리를 전부 본다: `epcList`(관측·커미셔닝) · `parentID`(집약의 부모) ·\n * `childEPCs`(집약의 자식) · `inputEPCList`·`outputEPCList`(변환의 입출력).\n */\nexport function touchedItemKeys(envelope: any): Set<string> | null {\n  const type = envelope?.eventType\n  if (typeof type !== 'string') return null\n  const d = envelope?.data ?? envelope\n  if (!d || typeof d !== 'object') return null\n\n  if (type.startsWith('energy.') || ITEM_FREE_EVENTS.has(type)) return new Set()\n  /* EPCIS 밖의 낯선 낱말 — 무엇을 바꿨는지 우리가 모른다. */\n  if (!type.startsWith('epcis.')) return null\n\n  const out = new Set<string>()\n  for (const v of d.epcList ?? []) push(out, v)\n  for (const v of d.childEPCs ?? []) push(out, v)\n  for (const v of d.inputEPCList ?? []) push(out, v)\n  for (const v of d.outputEPCList ?? []) push(out, v)\n  push(out, d.parentID)\n\n  /*\n   * 개체를 하나도 말하지 않은 EPCIS 사건은 **부류 수량**으로 말한 것이다(`quantityList`). 그 부류의\n   * 물품이 어느 것인지는 여기서 알 수 없으므로 전부 다시 만든다.\n   */\n  if (!out.size) return null\n\n  return out\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/headless-twin",
-  "version": "10.0.11",
+  "version": "10.0.13",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh <heartyoh@hatiolab.com>",
@@ -22,16 +22,16 @@
     "clean": "npm run clean:server && npm run clean:shared",
     "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.shared.json --noEmit",
-    "test": "node --test test/*.test.ts",
+    "test": "node --import ./test/resolve-ts-siblings.mjs --test test/*.test.ts",
     "build:shared": "tsc -p tsconfig.shared.json",
     "clean:shared": "rm -rf dist-shared tsconfig.shared.tsbuildinfo"
   },
   "dependencies": {
-    "@operato/twin-kernel": "^0.7.30",
-    "@things-factory/auth-base": "^10.0.10",
-    "@things-factory/cache-service": "^10.0.10",
+    "@operato/twin-kernel": "^0.7.53",
+    "@things-factory/auth-base": "^10.0.13",
+    "@things-factory/cache-service": "^10.0.13",
     "@things-factory/env": "^10.0.8",
-    "@things-factory/shell": "^10.0.10"
+    "@things-factory/shell": "^10.0.13"
   },
-  "gitHead": "3d26d911797ba51b29402bf26ff7888a46fccad4"
+  "gitHead": "808b3b9e3bf15c058316ec4c73455108df7722aa"
 }

package/server/engine/canonical-ingest.ts

@@ -1,12 +1,16 @@
-import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, isEnergyRecord,
-  isEnergyEquipmentRecord, type AdapterRule, type EnergyRecord,
-  type EnergyEquipmentRecord, type IngestResult } from '@operato/twin-kernel'
+import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, ingestOperationalRecords, isAggregationRecord, isTransformationRecord,
+  isEnergyRecord, isEnergyEquipmentRecord, isOperationalRecord, type AdapterRule, type EnergyRecord,
+  type EnergyEquipmentRecord, type OperationalRecord, type IngestResult } from '@operato/twin-kernel'
 
 /*
  * 정규 레코드 → 커널 검증 ACL → CanonicalEnvelope (P1 seam 코어).
  * 순수(커널만 의존; shell·integration-base 무의존 → node:test 검증 가능).
  * 매핑(레거시 스키마 → 정규)은 이 앞 단계(jsonata step 또는 커넥터 openLiveFeed)가 끝낸다.
- * 여기 도착하는 레코드는 이미 정규 필드다: { epc, action, bizStep, disposition?, readPoint?, bizLocation? }
+ * 여기 도착하는 레코드는 이미 정규 필드다 — 어휘마다 자기 필드 이름이 계약이다:
+ *   EPCIS 품목 { epc, action, bizStep, disposition?, readPoint?, bizLocation? }
+ *   에너지 계량 { meterId, kW?, kWh?, … } · 설비 에너지 { equipmentId, generatedKW?, soc?, … }
+ *   담김(적재) { parentID, childEPCs[] | childQuantityList[], action, bizStep, … }
+ *   운영 사실 { taskId | moverId | personId | assetId | orderId, status, … }  // vocabulary-guard: allow 저널 와이어 필드
  * 커널은 objectEvent 구성 + EPCIS 검증(위반=오염 차단) + 봉투 래핑만(방언 없음).
  *
  * 두 소비처가 이 단일 코어를 공유(중복 금지):
@@ -15,7 +19,7 @@ import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, isEnergyReco
  * SoT: design/integration/face2-adapters.md §5(seam)·§7(매핑=밖, 검증=커널).
  */
 
-/** 고정 정규 매핑(방언 아님 — 필드명 자체가 정규 계약). sourceType='twin' 으로 매칭. */
+/** 고정 정규 매핑(방언 아님 — 필드명 자체가 정규 계약). `sourceType` 으로 어느 품목 사실인지 고른다. */
 const TWIN_INGEST_RULES: AdapterRule[] = [
   {
     sourceType: 'twin',
@@ -25,14 +29,66 @@ const TWIN_INGEST_RULES: AdapterRule[] = [
       bizStep: '$.bizStep',
       disposition: '$.disposition',
       epc: '$.epc',
+      /* 비직렬 수량 — 개체 없이 「이 자리에 이 품목이 얼마 남았다」만 오는 관측이 있다. */
+      quantityList: '$.quantityList',
+      readPoint: '$.readPoint',
+      bizLocation: '$.bizLocation'
+    }
+  },
+  {
+    /* **변환의 사실** — 무엇으로 무엇이 되었나. 이름은 표준의 것을 그대로 쓴다(갈래 판정이 그 이름을 본다). */
+    sourceType: 'twin-transformation',
+    mapping: {
+      type: 'TransformationEvent',
+      bizStep: '$.bizStep',
+      disposition: '$.disposition',
+      inputEPCList: '$.inputEPCList',
+      inputQuantityList: '$.inputQuantityList',
+      outputEPCList: '$.outputEPCList',
+      outputQuantityList: '$.outputQuantityList',
+      transformationID: '$.transformationID',
+      readPoint: '$.readPoint',
+      bizLocation: '$.bizLocation'
+    }
+  },
+  {
+    /*
+     * **담김의 사실** — 무엇이 무엇에 실렸나(팔레트·상자). 오래 비어 있던 자리다: 관측 리듀서는 이 사실을
+     * 받으면 자식 물품에 `parent` 를 붙이는데, 문이 `ObjectEvent` 하나만 알아서 원본은 적재를 말할 길이
+     * 없었다(시뮬 원본을 붙여 돌려 보고서야 로그로 드러났다).
+     */
+    sourceType: 'twin-aggregation',
+    mapping: {
+      type: 'AggregationEvent',
+      action: '$.action',
+      bizStep: '$.bizStep',
+      disposition: '$.disposition',
+      parentID: '$.parentID',
+      childEPCs: '$.childEPCs',
+      /* 낱개 식별자 없이 **수량으로** 담긴 자식(「이 품번 40개」) — 입고·포장이 이 모양으로 온다. */
+      childQuantityList: '$.childQuantityList',
       readPoint: '$.readPoint',
       bizLocation: '$.bizLocation'
     }
   }
 ]
 
+/** 개체 관측 — 물건 하나가 어디서 무엇이 됐나. */
 export interface CanonicalRecord {
-  epc: string
+  /**
+   * 개체 하나의 식별자. **`quantityList` 를 쓰면 없어도 된다** — 낱개 번호가 없는 자재(밀가루 3.5kg)는
+   * 개체가 없다. 둘 다 없으면 무엇을 관측했는지 말하지 않은 것이므로 커널 매핑이 거부한다.
+   */
+  epc?: string
+  /**
+   * 클래스와 수량 — `{ epcClass, quantity, uom? }`. **잔량 절대값을 싣는다**(「얼마 뺐다」가 아니라
+   * 「얼마 남았다」). 그래야 사건 하나를 놓쳐도 다음 사건이 정답을 다시 말해 주고 오차가 쌓이지 않는다.
+   *
+   * 담김(`childQuantityList`)이 하루 먼저 이 자리를 받았다 — 그때와 같은 이유다. 원본이 비직렬 수량을
+   * 말할 길이 없어서, 그것이 주된 경로인 시스템(식품 제조 MES)은 라이브를 낼 수 없었다. 커널의
+   * 관측 리듀서는 처음부터 이 값을 읽었고 문만 없었다.
+   */
+  quantityList?: { epcClass: string; quantity?: number; uom?: string }[]
   action: string // ADD | OBSERVE | DELETE
   bizStep: string
   disposition?: string
@@ -40,13 +96,66 @@ export interface CanonicalRecord {
   bizLocation?: string
 }
 
+/**
+ * 담김 관측 — **부모와 자식**으로 말한다. 자리 필드는 개체 관측과 같은 이름이다(문자열).
+ *
+ * 이름은 표준의 것을 그대로 쓴다(`parentID`·`childEPCs`) — 여기서 다시 지으면 매핑이 번역이 되고,
+ * 같은 사실에 두 어휘가 생긴다.
+ */
+/**
+ * 변환 관측 — **무엇으로 무엇이 되었나.** 입력과 출력이 **한 사실에 함께** 있어야 계보가 남는다.
+ *
+ * 따로 보내면(「이 로트가 없어졌다」와 「이 제품이 생겼다」) 그 둘을 이을 근거가 없다. 그래서 표준이
+ * 한 사건에 둘을 담고, 우리 레코드도 같은 모양이다.
+ *
+ * 이름은 **표준의 것을 그대로** 쓴다(`inputQuantityList` 등). 갈래 판정이 이 이름으로 이루어지므로
+ * 커넥터 낱말(`consumed`·`produced`)로 담으면 판정되지 않는다 — 커넥터가 정규 이름으로 담아 보내고
+ * 매핑은 그 안에서 값을 고른다.
+ *
+ * **없는 쪽은 필드를 만들지 않는다.** 빈 배열을 실으면 「없다」고 말하는 것이 된다. 소실(N→0)과
+ * 생성(0→N)도 표준이 인정하는 변환이다.
+ *
+ * `transformationID` 가 한 오더의 여러 단계를 잇는다 — 소비를 먼저 알고 산출을 나중에 알게 되는 원본에서
+ * 그 둘을 묶는 유일한 자리다.
+ */
+export interface CanonicalTransformationRecord {
+  /** 개체로 소비된 것. */
+  inputEPCList?: string[]
+  /** 클래스와 수량으로 소비된 것 — 로트 단위 소비가 이 자리다. */
+  inputQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
+  outputEPCList?: string[]
+  outputQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
+  /** 한 오더의 여러 단계를 잇는 식별자. */
+  transformationID?: string
+  bizStep: string
+  disposition?: string
+  readPoint?: string
+  bizLocation?: string
+}
+
+export interface CanonicalAggregationRecord {
+  parentID: string
+  /** 개체로 담긴 자식. 수량으로만 담겼으면 없다(둘 중 하나는 있어야 한다). */
+  childEPCs?: string[]
+  /** 수량으로 담긴 자식 — `{ epcClass, quantity, uom? }`. 값의 옳고 그름은 커널 검증이 본다. */
+  childQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
+  action: string // ADD(담다) | DELETE(풀다) | OBSERVE
+  bizStep: string
+  disposition?: string
+  readPoint?: string
+  bizLocation?: string
+}
+
 /** 정규 레코드[] → 검증된 CanonicalEnvelope[] (+ 거부분). 순수 함수. 단일→객체도 배열로 정규화. */
 export function ingestCanonicalRecords(
   records:
     | CanonicalRecord
+    | CanonicalAggregationRecord
+    | CanonicalTransformationRecord
     | EnergyRecord
     | EnergyEquipmentRecord
-    | (CanonicalRecord | EnergyRecord | EnergyEquipmentRecord)[]
+    | OperationalRecord
+    | (CanonicalRecord | CanonicalAggregationRecord | CanonicalTransformationRecord | EnergyRecord | EnergyEquipmentRecord | OperationalRecord)[]
     | undefined
     | null,
   tenantId: string,
@@ -54,29 +163,69 @@ export function ingestCanonicalRecords(
 ): IngestResult {
   const arr = Array.isArray(records) ? records : records ? [records] : []
   /*
-   * **어휘가 둘이다** — 물류(EPCIS)와 에너지. 예전에는 이 함수가 무조건 `ObjectEvent` 를 만들었고,
-   * 그래서 계측을 이 길로 넣으면 `epc` 가 없어 거부되거나(그나마 나은 쪽) 엉뚱한 물품 관측이 됐다.
+   * **어휘가 넷이다** — 물류(EPCIS)·에너지 계량·설비 에너지·운영 사실. 예전에는 이 함수가 무조건
+   * `ObjectEvent` 를 만들었고, 그래서 계측을 이 길로 넣으면 `epc` 가 없어 거부되거나(그나마 나은 쪽)
+   * 엉뚱한 물품 관측이 됐다.
+   *
+   * 물류 어휘 안에는 모양이 둘이다(개체 관측 `epc` / 담김 `parentID`+`childEPCs`).
    *
-   * 판정은 커널이 한 곳에서 한다(`isEnergyRecord`) — 여기서 다시 짐작하면 소비처마다 답이 달라진다.
-   * 봉투는 같은 것을 쓰므로 아래 소비처(미러·저널·방송)는 이 갈림을 알 필요가 없다.
+   * 판정은 커널이 한 곳에서 한다(`isEnergyRecord`·`isOperationalRecord`·`isAggregationRecord`) — 여기서 다시 짐작하면
+   * 소비처마다 답이 달라진다. 봉투는 같은 것을 쓰므로 아래 소비처(미러·저널·브로드캐스팅)는 이 갈림을 알
+   * 필요가 없다.
    */
   const energy = arr.filter(isEnergyRecord) as EnergyRecord[]
   /* 세 번째 어휘 — 설비가 낸 자기 에너지 상태(발전·저장·감축 여지·개폐 위치). 계량과 갈라 두는
      이유는 커널에 적혀 있다: 계량은 구간에 누적되고, 이것들은 그 설비의 지금이다. */
   const energyEquipment = arr.filter(isEnergyEquipmentRecord) as unknown as EnergyEquipmentRecord[]
-  const epcis = arr.filter(r => !isEnergyRecord(r) && !isEnergyEquipmentRecord(r)) as CanonicalRecord[]
+  /*
+   * 네 번째 어휘 — **운영 사실**(작업·설비·사람·자산·오더·품질). 관측 리듀서는 이것을 오래전부터
+   * 접었는데 **들어올 문이 없었다**: 원본이 「이 작업이 끝났다」를 말할 길이 없어 시뮬 커널만 그것을
+   * 아는 상태가 남았다(같은 화면이 두 구동에서 다른 것을 말한다).
+   */
+  const operational = arr.filter(isOperationalRecord) as OperationalRecord[]
+  const epcis = arr.filter(r => !isEnergyRecord(r) && !isEnergyEquipmentRecord(r) && !isOperationalRecord(r)) as (CanonicalRecord | CanonicalAggregationRecord | CanonicalTransformationRecord)[]
 
+  /* 품목 어휘 안에서도 갈림이 있다(개체 관측 / 담김) — 그 판정도 커널의 것을 부른다. */
   const epcisResult = epcis.length
-    ? ingest(epcis.map(r => ({ ...r, sourceType: 'twin' })), TWIN_INGEST_RULES, { tenantId, defaultEventTime })
+    ? ingest(
+        epcis.map(r => ({
+          ...r,
+          /* 판정은 커널이 한 곳에서 한다 — 여기서 다시 짐작하면 소비처마다 답이 달라진다. */
+          sourceType: isTransformationRecord(r)
+            ? 'twin-transformation'
+            : isAggregationRecord(r)
+              ? 'twin-aggregation'
+              : 'twin'
+        })),
+        TWIN_INGEST_RULES,
+        /*
+         * **레코드가 시각을 말하면 그것을 쓴다** (2026-08-23).
+         *
+         * `eventTimePath` 를 주지 않던 동안 이 경로는 **언제나 폴링 시각**을 썼다(`defaultEventTime`).
+         * 그래서 커넥터가 이미 싣고 있던 `eventTime`(변환 레코드의 `finishedAt` 등)이 **조용히
+         * 무시됐다** — 커넥터를 붙인 쪽은 그것이 먹는다고 믿고 있었고, 어디에도 오류가 나지 않았다.
+         *
+         * 무엇이 걸렸나: 계보(변환)의 시각이다. 4월에 만든 로트가 8월에 만들어진 것으로 저널에 남았다.
+         * 그리고 실측 소요를 재는 폴드가 봉투 시각을 쓰므로(§`kpi-fold`: `workMs = 완료 − 첫 착수`),
+         * 폴링 간격을 작업시간으로 배울 수 있었다 — 못 배우는 것보다 나쁘다.
+         *
+         * 레코드에 `eventTime` 이 없으면 커널이 조용히 기본값으로 떨어진다(§`resolve` — 없는 값은
+         * 오류가 아니다). 그래서 이 한 줄이 기존 경로를 막지 않는다: 시각을 말하는 레코드만 사실이 된다.
+         */
+        { tenantId, defaultEventTime, eventTimePath: 'eventTime' }
+      )
     : { accepted: [], rejected: [] }
   const energyResult = energy.length ? ingestEnergyRecords(energy, { tenantId, defaultEventTime }) : { accepted: [], rejected: [] }
   const equipmentResult = energyEquipment.length
     ? ingestEnergyEquipmentRecords(energyEquipment, { tenantId, defaultEventTime })
     : { accepted: [], rejected: [] }
+  const operationalResult = operational.length
+    ? ingestOperationalRecords(operational, { tenantId, defaultEventTime })
+    : { accepted: [], rejected: [] }
 
   /* 거부분을 합쳐 돌려준다 — 어느 어휘에서 거부됐는지는 이유 문구가 말한다. */
   return {
-    accepted: [...epcisResult.accepted, ...energyResult.accepted, ...equipmentResult.accepted],
-    rejected: [...epcisResult.rejected, ...energyResult.rejected, ...equipmentResult.rejected]
+    accepted: [...epcisResult.accepted, ...energyResult.accepted, ...equipmentResult.accepted, ...operationalResult.accepted],
+    rejected: [...epcisResult.rejected, ...energyResult.rejected, ...equipmentResult.rejected, ...operationalResult.rejected]
   }
 }

package/server/engine/command-routing.ts

@@ -57,7 +57,7 @@ export function routeCommand(inst: RoutableInstance | undefined, ownedByCaller:
   if (!type) return { target: 'reject', errorCode: 'unknown-command' }
 
   if (inst.mode !== 'live') {
-    /* 시뮬 — 커널이 세계다. 런타임이 없으면 예외를 던지지 않고 이유를 말한다. */
+    /* 시뮬 — 커널이 세계다. 런타임이 없으면 오류를 내지 않고 이유를 말한다. */
     return inst.hasRuntime ? { target: 'runtime' } : { target: 'reject', errorCode: 'no-runtime' }
   }
 

package/server/engine/declared-stimulus.ts

@@ -0,0 +1,66 @@
+/*
+ * **자극은 원본이 선언한다** — 트윈이 아니라.
+ *
+ * ── 무엇이 났나 (2026-08-19) ────────────────────────────────────────────────
+ * 데모의 자극(시나리오)은 시드 코드가 **메모리에만** 실었다: `runtime.scenario.load(...)`. 그래서 트윈을
+ * 재기동하면 자극이 사라지고, 구조만 서 있는 트윈이 남는다 — 작업 0·오더 0. 「살아 있는 데모」가
+ * **첫 재기동까지만** 사는 것이다(오늘 서버를 여러 번 띄우는 동안 실제로 그 상태였다).
+ *
+ * ── 왜 트윈에 저장하지 않나 (ADR-0029 · plans/simulator-as-source.md §4) ────
+ * 자극은 **원본의 거동**이다: 무엇이 들어오고 무슨 주문이 나는지는 시뮬레이터(원본)가 정하는 사실이고,
+ * 트윈은 그것을 반영한다. 트윈에 새 축을 만들면 ADR-0029 가 나중에 걷어내야 하는 표면이 하나 늘고
+ * (그 계획서의 §2·§5 가 이미 그 부담을 적어 두었다), 원본에 두면 그 계획의 **첫 조각 앞자리**가 된다:
+ * 지금은 호스트가 읽어 커널에 싣고, 나중에 `openLiveFeed` 뒤로 옮기면 같은 선언이 그대로 쓰인다.
+ *
+ * 그래서 집은 `TwinReference.connectionConfig.scenario` — 어댑터별 설정 자리(이미 `simple-json`)다.
+ *
+ * ── 판정을 순수 함수로 (이 파일) ────────────────────────────────────────────
+ * 「이 트윈에 저장된 자극을 실을 것인가」에는 사람이 틀리기 쉬운 갈림이 셋 있다: 미러에 실으면 **현실을
+ * 오염**시키고, 잘못된 선언을 실으면 **다음 틱에서 서버가 내려가고**(실제로 그 이력이 있다), 시나리오
+ * 엔진이 없는 런타임에 실으면 조용히 아무 일도 없다. 그래서 판정을 값으로 만들고 시험한다.
+ */
+
+/** 자극을 실을지 말지 — 그리고 왜. 부르는 쪽은 이 답만 보고 움직인다. */
+export type StimulusPlan =
+  /** 실어라 — 검사를 통과한 선언. */
+  | { action: 'load'; scenario: any }
+  /**
+   * 싣지 않는다 — 그 이유.
+   *  · `none`        — 원본이 자극을 선언하지 않았다(정상: 정적 구조만 반영하는 트윈)
+   *  · `mirror`      — 미러다. 외부 실물이 진실인 트윈에 우리가 자극을 만들면 그것은 현실이 아니다
+   *  · `no-engine`   — 이 런타임에 시나리오 엔진이 없다(관측 구동 커널)
+   *  · `invalid`     — 선언이 커널 규약을 어긴다. **싣지 않고 말한다**(다음 틱에서 터지게 두지 않는다)
+   */
+  | { action: 'skip'; reason: 'none' | 'observed' | 'no-engine' | 'invalid'; detail?: string }
+
+/**
+ * 저장된 자극 선언을 읽어 **실을지 판정한다** — 커널 검사기를 그대로 쓴다(규칙을 두 벌로 만들지 않는다).
+ *
+ * `validate` 는 커널의 `validateScenario` 를 넘긴다(호스트가 커널 타입에 묶이지 않게 함수로 받는다).
+ * 검사기가 없으면 **싣지 않는다**: 검사할 수 없는 선언을 태우는 것이 가장 비싼 선택이다(서버가 내려간
+ * 이력이 있다).
+ */
+export function planStimulus(
+  config: any,
+  runtime: { hasScenarioEngine: boolean; mode?: 'sim' | 'live' },
+  validate?: (scenario: any) => { ok: boolean; errorCode?: string; errorParams?: any } | { ok: false; errorCode: string }
+): StimulusPlan {
+  const scenario = config?.scenario
+  if (!scenario || typeof scenario !== 'object') return { action: 'skip', reason: 'none' }
+  /* 관측 트윈을 먼저 막는다 — 「엔진이 없다」로 답하면 이유가 흐려진다(애초에 실을 수 없는 트윈이다). */
+  if (runtime.mode === 'live') return { action: 'skip', reason: 'observed' }
+  if (!runtime.hasScenarioEngine) return { action: 'skip', reason: 'no-engine' }
+  if (!validate) return { action: 'skip', reason: 'invalid', detail: 'no validator available' }
+  const v = validate(scenario)
+  if (!v?.ok) return { action: 'skip', reason: 'invalid', detail: (v as any)?.errorCode ?? 'rejected' }
+  return { action: 'load', scenario }
+}
+
+/**
+ * 선언을 원본 설정에 얹는다(순수) — **기존 설정을 지우지 않는다.**
+ *
+ * 어댑터 설정에는 접속 정보가 함께 산다. 자극을 넣으면서 그 옆을 덮으면 다음 재동기가 원본을 못 찾는다.
+ */
+export function withStimulus(config: any, scenario: any): any {
+  return { ...(config ?? {}), scenario }
+}

package/server/engine/index.ts

@@ -12,6 +12,7 @@ export * from '@things-factory/headless-twin/dist-shared/entity-delta.js'
 export * from '@things-factory/headless-twin/dist-shared/twin-level.js'
 /* 부하 계기판 — 어떤 작업이 이벤트 루프를 얼마나 쓰는지. */
 export * from './load-meter.js'
+export * from './loop-lag.js'
 /* 런타임 레지스트리 키 규약 — 소비처(다른 키 캐시·테스트)가 `:` 를 다시 적지 않게 함께 내보낸다. */
 export * from './runtime-key.js'
 export * from './kpi-query.js'
@@ -20,6 +21,11 @@ export * from './travel-estimator.js'
 export * from './measured-estimator.js'
 export * from './model-basis.js'
 export * from './live-feed-registry.js'
+/* 동기화 건강 — 「이 트윈이 현장과 맞춰지고 있나」. 판정·추이·사유·표본. */
+export * from './ingest-health.js'
 /* 로컬 선언(현장·트윈) — 소비처(twin-ai 도구)가 명세·검사 규칙을 다시 적지 않게. */
 export * from './local-declarations.js'
 export * from './operation-basis.js'
+export * from './measured-yield.js'
+export * from './declared-stimulus.js'
+export * from './integration-coverage.js'