@things-factory/headless-twin 10.0.12 → 10.0.13

package/dist-server/engine/canonical-ingest.d.ts

@@ -1,7 +1,24 @@
 import { type EnergyRecord, type EnergyEquipmentRecord, type OperationalRecord, type IngestResult } from '@operato/twin-kernel';
 /** 개체 관측 — 물건 하나가 어디서 무엇이 됐나. */
 export interface CanonicalRecord {
-    epc: string;
+    /**
+     * 개체 하나의 식별자. **`quantityList` 를 쓰면 없어도 된다** — 낱개 번호가 없는 자재(밀가루 3.5kg)는
+     * 개체가 없다. 둘 다 없으면 무엇을 관측했는지 말하지 않은 것이므로 커널 매핑이 거부한다.
+     */
+    epc?: string;
+    /**
+     * 클래스와 수량 — `{ epcClass, quantity, uom? }`. **잔량 절대값을 싣는다**(「얼마 뺐다」가 아니라
+     * 「얼마 남았다」). 그래야 사건 하나를 놓쳐도 다음 사건이 정답을 다시 말해 주고 오차가 쌓이지 않는다.
+     *
+     * 담김(`childQuantityList`)이 하루 먼저 이 자리를 받았다 — 그때와 같은 이유다. 원본이 비직렬 수량을
+     * 말할 길이 없어서, 그것이 주된 경로인 시스템(식품 제조 MES)은 라이브를 낼 수 없었다. 커널의
+     * 관측 리듀서는 처음부터 이 값을 읽었고 문만 없었다.
+     */
+    quantityList?: {
+        epcClass: string;
+        quantity?: number;
+        uom?: string;
+    }[];
     action: string;
     bizStep: string;
     disposition?: string;
@@ -14,6 +31,44 @@ export interface CanonicalRecord {
  * 이름은 표준의 것을 그대로 쓴다(`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;
     /** 개체로 담긴 자식. 수량으로만 담겼으면 없다(둘 중 하나는 있어야 한다). */
@@ -31,4 +86,4 @@ export interface CanonicalAggregationRecord {
     bizLocation?: string;
 }
 /** 정규 레코드[] → 검증된 CanonicalEnvelope[] (+ 거부분). 순수 함수. 단일→객체도 배열로 정규화. */
-export declare function ingestCanonicalRecords(records: CanonicalRecord | CanonicalAggregationRecord | EnergyRecord | EnergyEquipmentRecord | OperationalRecord | (CanonicalRecord | CanonicalAggregationRecord | EnergyRecord | EnergyEquipmentRecord | OperationalRecord)[] | undefined | null, tenantId: string, defaultEventTime: string): IngestResult;
+export declare function ingestCanonicalRecords(records: CanonicalRecord | CanonicalAggregationRecord | CanonicalTransformationRecord | EnergyRecord | EnergyEquipmentRecord | OperationalRecord | (CanonicalRecord | CanonicalAggregationRecord | CanonicalTransformationRecord | EnergyRecord | EnergyEquipmentRecord | OperationalRecord)[] | undefined | null, tenantId: string, defaultEventTime: string): IngestResult;

package/dist-server/engine/canonical-ingest.js

@@ -28,6 +28,24 @@ const TWIN_INGEST_RULES = [
             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'
         }
@@ -64,7 +82,7 @@ function ingestCanonicalRecords(records, tenantId, defaultEventTime) {
      * 물류 어휘 안에는 모양이 둘이다(개체 관측 `epc` / 담김 `parentID`+`childEPCs`).
      *
      * 판정은 커널이 한 곳에서 한다(`isEnergyRecord`·`isOperationalRecord`·`isAggregationRecord`) — 여기서 다시 짐작하면
-     * 소비처마다 답이 달라진다. 봉투는 같은 것을 쓰므로 아래 소비처(미러·저널·방송)는 이 갈림을 알
+     * 소비처마다 답이 달라진다. 봉투는 같은 것을 쓰므로 아래 소비처(미러·저널·브로드캐스팅)는 이 갈림을 알
      * 필요가 없다.
      */
     const energy = arr.filter(twin_kernel_1.isEnergyRecord);
@@ -80,7 +98,30 @@ function ingestCanonicalRecords(records, tenantId, defaultEventTime) {
     const epcis = arr.filter(r => !(0, twin_kernel_1.isEnergyRecord)(r) && !(0, twin_kernel_1.isEnergyEquipmentRecord)(r) && !(0, twin_kernel_1.isOperationalRecord)(r));
     /* 품목 어휘 안에서도 갈림이 있다(개체 관측 / 담김) — 그 판정도 커널의 것을 부른다. */
     const epcisResult = epcis.length
-        ? (0, twin_kernel_1.ingest)(epcis.map(r => ({ ...r, sourceType: (0, twin_kernel_1.isAggregationRecord)(r) ? 'twin-aggregation' : 'twin' })), TWIN_INGEST_RULES, { tenantId, defaultEventTime })
+        ? (0, twin_kernel_1.ingest)(epcis.map(r => ({
+            ...r,
+            /* 판정은 커널이 한 곳에서 한다 — 여기서 다시 짐작하면 소비처마다 답이 달라진다. */
+            sourceType: (0, twin_kernel_1.isTransformationRecord)(r)
+                ? 'twin-transformation'
+                : (0, twin_kernel_1.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 ? (0, twin_kernel_1.ingestEnergyRecords)(energy, { tenantId, defaultEventTime }) : { accepted: [], rejected: [] };
     const equipmentResult = energyEquipment.length

package/dist-server/engine/canonical-ingest.js.map

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

package/dist-server/engine/command-routing.js

@@ -42,7 +42,7 @@ function routeCommand(inst, ownedByCaller, type) {
     if (!type)
         return { target: 'reject', errorCode: 'unknown-command' };
     if (inst.mode !== 'live') {
-        /* 시뮬 — 커널이 세계다. 런타임이 없으면 예외를 던지지 않고 이유를 말한다. */
+        /* 시뮬 — 커널이 세계다. 런타임이 없으면 오류를 내지 않고 이유를 말한다. */
         return inst.hasRuntime ? { target: 'runtime' } : { target: 'reject', errorCode: 'no-runtime' };
     }
     /* 미러 — 실 프로세스 변경은 아웃바운드 어댑터의 몫이고 아직 결선되지 않았다. */

package/dist-server/engine/command-routing.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-routing.js","sourceRoot":"","sources":["../../server/engine/command-routing.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAgCH,oCAYC;AA1CD,6CAA6C;AAC7C,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAS,CAAC,eAAe,CAAC,CAAC,CAAA;AAoB9D,uCAAuC;AAChC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAAvE,QAAA,WAAW,eAA4D;AAEpF;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,IAAkC,EAAE,aAAsB,EAAE,IAAY;IACnG,IAAI,CAAC,IAAI,IAAI,CAAC,aAAa;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;IAClF,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAA;IAEpE,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzB,gDAAgD;QAChD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA;IAChG,CAAC;IAED,iDAAiD;IACjD,IAAI,IAAA,mBAAW,EAAC,IAAI,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,qBAAqB,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,EAAE,CAAA;IAC3G,OAAO,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA;AACtG,CAAC","sourcesContent":["/*\n * 커맨드 라우팅 판정 — **순수**. \"이 커맨드를 누구에게 보낼 것인가\" 만 정한다.\n * 실제 dispatch·저널 기록은 엔진이 한다(`design/plans/command-routing.md` §1·§4 P0).\n *\n * ── 왜 떼어냈나 ─────────────────────────────────────────────────────────────\n * 예전에는 리졸버가 `inst.runtime.dispatch(...)` 를 곧바로 불렀다. `runtime` 은 **시뮬 경로에서만**\n * 만들어지므로 실물을 비추는 트윈(mirror)에서는 그 한 줄이 `TypeError` 로 터졌다 — 조치 채널이\n * 통째로 닿지 않았고, 사용자에게는 이유 있는 거절이 아니라 그냥 실패였다.\n *\n * 판정이 코드 한가운데 있으면 이런 부류를 테스트로 못 잡는다(엔진은 DB·TypeORM 을 물고 있어 단위\n * 테스트가 불러올 수 없다). 그래서 판정만 순수하게 떼어 둔다 — `planWarmStart` 와 같은 이유다.\n *\n * ── 판정 규칙 = 권위 × 성격 ─────────────────────────────────────────────────\n * | 성격 \\ 모드      | 시뮬            | 미러(현실을 비춤)                    |\n * | 액추에이션        | 커널 런타임      | **거절**(아웃바운드 어댑터 미결선)     |\n * | 주석(확인 ack)    | 커널 런타임      | 관측 커널                            |\n *\n * 미러에서 액추에이션을 그냥 허용하면 **새 거짓말이 생긴다**: 트윈은 \"보류됨\" 이라 말하고 실 시스템은\n * 모른다. 조용히 커널만 바꾸지 않고, 이유를 밝혀 거절한다.\n *\n * 반면 확인(ack)은 액추에이션이 아니다 — 신호를 봤다는 트윈 쪽 주석이라 현실을 건드리지 않는다.\n * 미러에서도 성립해야 하므로 관측 커널로 보낸다.\n */\n\n/** 관측 쪽 주석 커맨드 — 현실을 바꾸지 않으므로 미러에서도 통과한다. */\nconst ANNOTATION_COMMANDS = new Set<string>(['attention.ack'])\n\n/** 라우팅에 필요한 인스턴스 사실만 — 엔진 객체를 그대로 받지 않는다(순수하게 유지). */\nexport interface RoutableInstance {\n  /** 'live' 면 현실을 비추는 트윈(미러). 그 외는 시뮬. */\n  mode?: string\n  /** 커널 런타임(tick/dispatch)이 붙어 있나 — 시뮬 경로에서만 만들어진다. */\n  hasRuntime: boolean\n  /** 관측 커널이 dispatch 를 받을 수 있나. */\n  hasKernelDispatch: boolean\n}\n\nexport type CommandRoute =\n  /** 커널 런타임으로(시뮬 — 커널이 세계다). */\n  | { target: 'runtime' }\n  /** 관측 커널로(미러 — 주석만). 방출된 사실은 저널 큐에 실어야 한다. */\n  | { target: 'kernel' }\n  /** 보내지 않는다. 사유는 언어 중립 코드 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */\n  | { target: 'reject'; errorCode: string; errorParams?: Record<string, string | number> }\n\n/** 이 커맨드가 실 프로세스를 바꾸는 것인가(= 액추에이션). */\nexport const isActuation = (type: string): boolean => !ANNOTATION_COMMANDS.has(type)\n\n/**\n * 어디로 보낼지 정한다.\n *\n * `inst` 가 없거나 호출자 도메인 소유가 아니면 **같은 사유로** 거절한다 — 존재 여부를 알려 주면\n * 다른 테넌트의 인스턴스 id 를 추측할 수 있다(있음/없음이 구별되면 그것이 정보다).\n */\nexport function routeCommand(inst: RoutableInstance | undefined, ownedByCaller: boolean, type: string): CommandRoute {\n  if (!inst || !ownedByCaller) return { target: 'reject', errorCode: 'no-instance' }\n  if (!type) return { target: 'reject', errorCode: 'unknown-command' }\n\n  if (inst.mode !== 'live') {\n    /* 시뮬 — 커널이 세계다. 런타임이 없으면 예외를 던지지 않고 이유를 말한다. */\n    return inst.hasRuntime ? { target: 'runtime' } : { target: 'reject', errorCode: 'no-runtime' }\n  }\n\n  /* 미러 — 실 프로세스 변경은 아웃바운드 어댑터의 몫이고 아직 결선되지 않았다. */\n  if (isActuation(type)) return { target: 'reject', errorCode: 'actuation-not-wired', errorParams: { type } }\n  return inst.hasKernelDispatch ? { target: 'kernel' } : { target: 'reject', errorCode: 'no-runtime' }\n}\n"]}
+{"version":3,"file":"command-routing.js","sourceRoot":"","sources":["../../server/engine/command-routing.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAgCH,oCAYC;AA1CD,6CAA6C;AAC7C,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAS,CAAC,eAAe,CAAC,CAAC,CAAA;AAoB9D,uCAAuC;AAChC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAAvE,QAAA,WAAW,eAA4D;AAEpF;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,IAAkC,EAAE,aAAsB,EAAE,IAAY;IACnG,IAAI,CAAC,IAAI,IAAI,CAAC,aAAa;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;IAClF,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAA;IAEpE,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzB,+CAA+C;QAC/C,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA;IAChG,CAAC;IAED,iDAAiD;IACjD,IAAI,IAAA,mBAAW,EAAC,IAAI,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,qBAAqB,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,EAAE,CAAA;IAC3G,OAAO,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA;AACtG,CAAC","sourcesContent":["/*\n * 커맨드 라우팅 판정 — **순수**. \"이 커맨드를 누구에게 보낼 것인가\" 만 정한다.\n * 실제 dispatch·저널 기록은 엔진이 한다(`design/plans/command-routing.md` §1·§4 P0).\n *\n * ── 왜 떼어냈나 ─────────────────────────────────────────────────────────────\n * 예전에는 리졸버가 `inst.runtime.dispatch(...)` 를 곧바로 불렀다. `runtime` 은 **시뮬 경로에서만**\n * 만들어지므로 실물을 비추는 트윈(mirror)에서는 그 한 줄이 `TypeError` 로 터졌다 — 조치 채널이\n * 통째로 닿지 않았고, 사용자에게는 이유 있는 거절이 아니라 그냥 실패였다.\n *\n * 판정이 코드 한가운데 있으면 이런 부류를 테스트로 못 잡는다(엔진은 DB·TypeORM 을 물고 있어 단위\n * 테스트가 불러올 수 없다). 그래서 판정만 순수하게 떼어 둔다 — `planWarmStart` 와 같은 이유다.\n *\n * ── 판정 규칙 = 권위 × 성격 ─────────────────────────────────────────────────\n * | 성격 \\ 모드      | 시뮬            | 미러(현실을 비춤)                    |\n * | 액추에이션        | 커널 런타임      | **거절**(아웃바운드 어댑터 미결선)     |\n * | 주석(확인 ack)    | 커널 런타임      | 관측 커널                            |\n *\n * 미러에서 액추에이션을 그냥 허용하면 **새 거짓말이 생긴다**: 트윈은 \"보류됨\" 이라 말하고 실 시스템은\n * 모른다. 조용히 커널만 바꾸지 않고, 이유를 밝혀 거절한다.\n *\n * 반면 확인(ack)은 액추에이션이 아니다 — 신호를 봤다는 트윈 쪽 주석이라 현실을 건드리지 않는다.\n * 미러에서도 성립해야 하므로 관측 커널로 보낸다.\n */\n\n/** 관측 쪽 주석 커맨드 — 현실을 바꾸지 않으므로 미러에서도 통과한다. */\nconst ANNOTATION_COMMANDS = new Set<string>(['attention.ack'])\n\n/** 라우팅에 필요한 인스턴스 사실만 — 엔진 객체를 그대로 받지 않는다(순수하게 유지). */\nexport interface RoutableInstance {\n  /** 'live' 면 현실을 비추는 트윈(미러). 그 외는 시뮬. */\n  mode?: string\n  /** 커널 런타임(tick/dispatch)이 붙어 있나 — 시뮬 경로에서만 만들어진다. */\n  hasRuntime: boolean\n  /** 관측 커널이 dispatch 를 받을 수 있나. */\n  hasKernelDispatch: boolean\n}\n\nexport type CommandRoute =\n  /** 커널 런타임으로(시뮬 — 커널이 세계다). */\n  | { target: 'runtime' }\n  /** 관측 커널로(미러 — 주석만). 방출된 사실은 저널 큐에 실어야 한다. */\n  | { target: 'kernel' }\n  /** 보내지 않는다. 사유는 언어 중립 코드 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */\n  | { target: 'reject'; errorCode: string; errorParams?: Record<string, string | number> }\n\n/** 이 커맨드가 실 프로세스를 바꾸는 것인가(= 액추에이션). */\nexport const isActuation = (type: string): boolean => !ANNOTATION_COMMANDS.has(type)\n\n/**\n * 어디로 보낼지 정한다.\n *\n * `inst` 가 없거나 호출자 도메인 소유가 아니면 **같은 사유로** 거절한다 — 존재 여부를 알려 주면\n * 다른 테넌트의 인스턴스 id 를 추측할 수 있다(있음/없음이 구별되면 그것이 정보다).\n */\nexport function routeCommand(inst: RoutableInstance | undefined, ownedByCaller: boolean, type: string): CommandRoute {\n  if (!inst || !ownedByCaller) return { target: 'reject', errorCode: 'no-instance' }\n  if (!type) return { target: 'reject', errorCode: 'unknown-command' }\n\n  if (inst.mode !== 'live') {\n    /* 시뮬 — 커널이 세계다. 런타임이 없으면 오류를 내지 않고 이유를 말한다. */\n    return inst.hasRuntime ? { target: 'runtime' } : { target: 'reject', errorCode: 'no-runtime' }\n  }\n\n  /* 미러 — 실 프로세스 변경은 아웃바운드 어댑터의 몫이고 아직 결선되지 않았다. */\n  if (isActuation(type)) return { target: 'reject', errorCode: 'actuation-not-wired', errorParams: { type } }\n  return inst.hasKernelDispatch ? { target: 'kernel' } : { target: 'reject', errorCode: 'no-runtime' }\n}\n"]}

package/dist-server/engine/index.d.ts

@@ -8,6 +8,7 @@ export * from '@things-factory/headless-twin/dist-shared/kpi-broadcast.js';
 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';
 export * from './spec-coverage.js';
@@ -15,7 +16,9 @@ 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';
 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';

package/dist-server/engine/index.js

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

package/dist-server/engine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/engine/index.ts"],"names":[],"mappings":";;;AAAA,2DAAgC;AAChC,gEAAqC;AACrC,wDAA6B;AAC7B,gEAAqC;AACrC,4DAAiC;AACjC,qEAAqE;AACrE,0DAA+B;AAC/B,qGAA0E;AAC1E,0DAA0D;AAC1D,oGAAyE;AACzE,4CAA4C;AAC5C,kGAAuE;AACvE,sCAAsC;AACtC,0DAA+B;AAC/B,gEAAgE;AAChE,2DAAgC;AAChC,yDAA8B;AAC9B,6DAAkC;AAClC,gEAAqC;AACrC,kEAAuC;AACvC,2DAAgC;AAChC,kEAAuC;AACvC,yDAAyD;AACzD,kEAAuC;AACvC,+DAAoC;AACpC,8DAAmC;AACnC,iEAAsC","sourcesContent":["export * from './twin-engine.js'\nexport * from './canonical-ingest.js'\nexport * from './kpi-fold.js'\nexport * from './property-effects.js'\nexport * from './kpi-baseline.js'\n/* 지표 정본 표(TWIN_METRIC)·목표 판정 — 소비처(twin-ai 등)가 지표 이름을 다시 열거하지 않게. */\nexport * from './kpi-target.js'\nexport * from '@things-factory/headless-twin/dist-shared/kpi-broadcast.js'\n/* 집약 채널 태그(접두사 + 트윈별 태그 생성) — 소비처가 문자열을 다시 적지 않게 내보낸다. */\nexport * from '@things-factory/headless-twin/dist-shared/entity-delta.js'\n/* 공간 계층의 단계 — 씬 표현·성과 카드·AI 가 같은 목록을 쓴다. */\nexport * from '@things-factory/headless-twin/dist-shared/twin-level.js'\n/* 부하 계기판 — 어떤 작업이 이벤트 루프를 얼마나 쓰는지. */\nexport * from './load-meter.js'\n/* 런타임 레지스트리 키 규약 — 소비처(다른 키 캐시·테스트)가 `:` 를 다시 적지 않게 함께 내보낸다. */\nexport * from './runtime-key.js'\nexport * from './kpi-query.js'\nexport * from './spec-coverage.js'\nexport * from './travel-estimator.js'\nexport * from './measured-estimator.js'\nexport * from './model-basis.js'\nexport * from './live-feed-registry.js'\n/* 로컬 선언(현장·트윈) — 소비처(twin-ai 도구)가 명세·검사 규칙을 다시 적지 않게. */\nexport * from './local-declarations.js'\nexport * from './operation-basis.js'\nexport * from './measured-yield.js'\nexport * from './declared-stimulus.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/engine/index.ts"],"names":[],"mappings":";;;AAAA,2DAAgC;AAChC,gEAAqC;AACrC,wDAA6B;AAC7B,gEAAqC;AACrC,4DAAiC;AACjC,qEAAqE;AACrE,0DAA+B;AAC/B,qGAA0E;AAC1E,0DAA0D;AAC1D,oGAAyE;AACzE,4CAA4C;AAC5C,kGAAuE;AACvE,sCAAsC;AACtC,0DAA+B;AAC/B,wDAA6B;AAC7B,gEAAgE;AAChE,2DAAgC;AAChC,yDAA8B;AAC9B,6DAAkC;AAClC,gEAAqC;AACrC,kEAAuC;AACvC,2DAAgC;AAChC,kEAAuC;AACvC,gDAAgD;AAChD,6DAAkC;AAClC,yDAAyD;AACzD,kEAAuC;AACvC,+DAAoC;AACpC,8DAAmC;AACnC,iEAAsC;AACtC,oEAAyC","sourcesContent":["export * from './twin-engine.js'\nexport * from './canonical-ingest.js'\nexport * from './kpi-fold.js'\nexport * from './property-effects.js'\nexport * from './kpi-baseline.js'\n/* 지표 정본 표(TWIN_METRIC)·목표 판정 — 소비처(twin-ai 등)가 지표 이름을 다시 열거하지 않게. */\nexport * from './kpi-target.js'\nexport * from '@things-factory/headless-twin/dist-shared/kpi-broadcast.js'\n/* 집약 채널 태그(접두사 + 트윈별 태그 생성) — 소비처가 문자열을 다시 적지 않게 내보낸다. */\nexport * from '@things-factory/headless-twin/dist-shared/entity-delta.js'\n/* 공간 계층의 단계 — 씬 표현·성과 카드·AI 가 같은 목록을 쓴다. */\nexport * from '@things-factory/headless-twin/dist-shared/twin-level.js'\n/* 부하 계기판 — 어떤 작업이 이벤트 루프를 얼마나 쓰는지. */\nexport * from './load-meter.js'\nexport * from './loop-lag.js'\n/* 런타임 레지스트리 키 규약 — 소비처(다른 키 캐시·테스트)가 `:` 를 다시 적지 않게 함께 내보낸다. */\nexport * from './runtime-key.js'\nexport * from './kpi-query.js'\nexport * from './spec-coverage.js'\nexport * from './travel-estimator.js'\nexport * from './measured-estimator.js'\nexport * from './model-basis.js'\nexport * from './live-feed-registry.js'\n/* 동기화 건강 — 「이 트윈이 현장과 맞춰지고 있나」. 판정·추이·사유·표본. */\nexport * from './ingest-health.js'\n/* 로컬 선언(현장·트윈) — 소비처(twin-ai 도구)가 명세·검사 규칙을 다시 적지 않게. */\nexport * from './local-declarations.js'\nexport * from './operation-basis.js'\nexport * from './measured-yield.js'\nexport * from './declared-stimulus.js'\nexport * from './integration-coverage.js'\n"]}

package/dist-server/engine/ingest-health.d.ts

@@ -0,0 +1,335 @@
+/** 추이 창 하나 — 제시·통과·거부·미전달, 그리고 **적힌 것**을 함께 든다. */
+export interface IngestWindow {
+    /** 창이 열린 시각(ms). */
+    startMs: number;
+    /** 창이 닫힌 시각(ms). 아직 채우는 중이면 `-1`. */
+    endMs: number;
+    /** 이 창에 제시된 레코드 수(거부 여부 무관). */
+    offered: number;
+    /** 그중 **매핑이 거부한** 수 — 처방은 매핑을 고치는 것이다. */
+    rejected: number;
+    /**
+     * 매핑은 통과했지만 **트윈에 닿지 못한** 수 — 처방은 트윈을 세우는 것이다.
+     *
+     * ── 왜 거부와 따로 세나 (2026-08-20에 겪었다) ─────────────────────────────
+     * 트윈이 라이브로 돌지 않으면 커널이 레코드를 **조용히 버린다**. 그런데 장부는 그것을 「통과」로 셌다.
+     * 화면이 「150 들어옴 · 150 통과 · 100%」라고 말하는 동안 150건은 바닥에 버려지고 있었다. 이 기능이
+     * 막으려던 바로 그것을 이 기능이 저지른 셈이다.
+     *
+     * 거부에 합치는 것도 답이 아니다 — 거부는 「매핑을 고쳐라」는 말이고, 여기서 필요한 말은 「트윈이 안
+     * 돌고 있다」다. **처방이 다르면 다른 수로 센다.**
+     */
+    undelivered: number;
+    /**
+     * 이 창에 **저널에 적힌 행** 수 — 「무엇이 남았나」.
+     *
+     * 유입과 다른 축이다: 시뮬 트윈은 받는 것 없이 자기가 낸 사실을 적는다(그래서 `offered` 는 0 이고
+     * `rows` 는 0 이 아니다). 이 칸이 없으면 그 트윈의 활동은 어느 추이에도 나타나지 않는다.
+     */
+    rows: number;
+    /**
+     * 그것을 적기 위해 **DB 를 두드린 횟수**(flush) — 「우리가 몇 번 갔나」.
+     *
+     * 행 수와 따로 세는 이유: 2026-08-20 에 고친 것이 바로 이 값이다(행마다 한 번 → 창당 한 번). 행만
+     * 세면 그 개선도, 되돌아가는 것도 보이지 않는다.
+     */
+    flushes: number;
+}
+/** 거부 표본 하나 — 매핑을 고치려면 실제 모양을 봐야 한다. */
+export interface RejectSample {
+    atMs: number;
+    /** 커널이 낸 사유. 우리가 다시 쓰지 않고 그대로 옮긴다. */
+    errors: string[];
+    /** 막힌 레코드의 직렬화. 길면 자르고, 잘랐다고 표시한다. */
+    record: string;
+    recordTruncated?: boolean;
+}
+export interface IngestLedger {
+    /** 지금 채우는 중인 창. `startMs < 0` 이면 아직 아무것도 받지 않았다. */
+    window: IngestWindow;
+    /** 닫힌 창들 — 오래된 것이 앞. 상한을 넘으면 앞에서 밀려난다. */
+    trend: IngestWindow[];
+    /** 추이에서 밀려난 창 수. */
+    trendDropped: number;
+    /** 누적 제시·거부·미전달. */
+    offered: number;
+    rejected: number;
+    undelivered: number;
+    /** 누적 — 적힌 행과 두드린 횟수. */
+    rows: number;
+    flushes: number;
+    /**
+     * 마지막으로 **적은** 시각. 한 번도 없으면 `-1`.
+     *
+     * 유입 시각(`lastAtMs`)과 갈라 두는 이유는 위 `recordJournalWrite` 주석에 있다 — 섞으면 끊긴 피드가
+     * 초록으로 보인다.
+     */
+    lastWriteAtMs: number;
+    /**
+     * 마지막으로 **버려진** 시각(ms). 한 번도 없으면 `-1`.
+     *
+     * 창과 따로 둔다: 미전달은 창이 닫히기 전에 알아야 한다(그 사이에도 사실은 계속 사라지고 있다).
+     */
+    lastUndeliveredAtMs: number;
+    /** 사유별 누적 건수와 **마지막으로 그 사유가 난 시각** — 고친 사유는 시각이 멈춘다. */
+    byReason: Record<string, {
+        count: number;
+        lastAtMs: number;
+    }>;
+    /**
+     * 사유 종류가 상한에 닿았나.
+     *
+     * **접힌 종류 수는 세지 않는다** — 그것을 세려면 이미 본 사유를 모두 기억해야 하고, 그 집합이
+     * 바로 이 상한으로 막으려던 무한한 집합이다. 접힌 **건수**는 `byReason[OTHER_REASON].count` 가 답한다.
+     */
+    reasonsCapped: boolean;
+    /** 표본을 이미 뜬 사유들 — 같은 사유를 다시 직렬화하지 않기 위한 색인(O(1) 조회). */
+    sampledReasons: Set<string>;
+    /** 최근 거부 표본. */
+    samples: RejectSample[];
+    /** 표본에서 밀려난 거부 건수. */
+    sampleDropped: number;
+    /** 마지막으로 무엇이든 받은 시각(ms). **한 번도 없으면 `-1`** — 0 으로 두면 시각 0 과 구별되지 않는다. */
+    lastAtMs: number;
+    /**
+     * **원본에 닿지 못한 사실** (2026-08-23) — 「받은 것이 없다」와 **다른 사실**이다.
+     *
+     * ── 무엇이 조용했나 ─────────────────────────────────────────────────────────
+     * 실 원본이 끊겼을 때(접속 시간 초과) 트윈의 **조회 가능한 상태 어디에도** 그 사실이 없었다.
+     * `recordIngest` 는 `onRecords` 가 불릴 때만 도달하고, 읽기가 실패하면 그 문에 오지 않는다.
+     * `TwinReference.lastError` 는 마스터 동기·접속 시험에만 적힌다.
+     *
+     * 그래서 화면이 볼 수 있는 것은 「새 사실이 없다」뿐이었고, 그것은 **「원본이 조용하다」와 구별되지
+     * 않는다.** 실증 데모 중에 원본이 끊기면 사용자가 원인을 찾을 수 없다.
+     *
+     * ── 왜 「몇 번」과 「언제부터」를 함께 두나 ──────────────────────────────────
+     * 한 번 실패한 것과 20분째 못 읽는 것은 다른 사실이다. 그 구별이 없으면 화면이 순간의 실패에 놀라거나
+     * 계속된 단절을 대수롭지 않게 말한다. 그래서 **연속 실패 수**와 **처음 실패한 시각**을 함께 든다.
+     *
+     * 성공하면 지운다 — 고쳐진 단절이 화면에 남아 있으면 그것도 거짓이다.
+     */
+    readFailure?: {
+        /** 연속 실패 수 — 성공 한 번에 0 으로 돌아간다. */
+        consecutive: number;
+        /** 이 단절이 **처음** 시작된 시각(ms). 연속이 끊기면 다시 정해진다. */
+        sinceMs: number;
+        /** 마지막 실패 시각(ms). */
+        lastAtMs: number;
+        /** 마지막 실패의 사유 — 사람이 읽는 한 줄(원본이 준 말 그대로). */
+        reason: string;
+        /** 어느 흐름에서 났나(어댑터가 말해 주면). 원본마다 흐름이 다르므로 열려 있다. */
+        stream?: string;
+    };
+}
+/**
+ * 읽기 실패를 장부에 적는다 — **받은 것이 없는 것과 가른다.**
+ *
+ * 연속 실패의 시작 시각을 지키는 것이 이 함수의 요점이다: 매번 새로 적으면 「20분째 못 읽는다」를
+ * 말할 수 없고, 화면은 늘 「방금 실패했다」만 보게 된다.
+ */
+export declare function recordReadFailure(ledger: IngestLedger, reason: string, nowMs: number, stream?: string): void;
+/**
+ * 읽기가 성공했다 — 단절 기록을 지운다.
+ *
+ * **빈 읽기도 성공이다**: 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이다. 그 둘을 같게 두면
+ * 조용한 원본이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
+ */
+export declare function clearReadFailure(ledger: IngestLedger): void;
+/** 창 길이 — 10분. 부하 계기판(10초)과 다른 값이라 이름을 따로 둔다(같은 이름이면 섞인다). */
+export declare const INGEST_WINDOW_MS = 600000;
+/**
+ * 이만큼 아무것도 오지 않으면 「유입 없음」이라 말한다.
+ *
+ * 창 하나와 같게 둔다 — 한 창을 통째로 비운 것은 실제로 「그 구간에 아무것도 오지 않았다」이고, 추이의
+ * 그 자리도 비게 된다. 그림과 알약이 같은 말을 하게 하려면 같은 길이여야 한다.
+ */
+export declare const STALE_AFTER_MS = 600000;
+/** 추이 보관 창 수 — 36창 × 10분 = 6시간. 「고친 것이 먹혔나」를 보기에 충분하고 메모리는 숫자 넷×36 이다. */
+export declare const TREND_LIMIT = 36;
+/**
+ * 사유 종류 상한.
+ *
+ * **없으면 메모리가 끝없이 자란다.** 사유 문구에 레코드마다 다른 값이 섞이는 커넥터가 하나만 있어도
+ * (`unknown bizStep "PUTAWAY_X17"`, `…X18`, …) 키가 무한히 늘어난다. 초당 1만 건 규모에서 이것은
+ * 미미한 오버헤드가 아니라 누수다.
+ *
+ * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 접었는지 함께 낸다**(조용히 자르지 않는다).
+ * 30종이면 고칠 곳을 찾기에 충분하다 — 목록을 훑는 일이 아니라 매핑 몇 줄을 고치는 일이다.
+ */
+export declare const REASON_LIMIT = 30;
+/** 상한을 넘긴 사유들이 모이는 칸. */
+export declare const OTHER_REASON = "(other reasons)";
+/**
+ * 표본 상한 — **사유마다 한 건**만 든다.
+ *
+ * 같은 사유 20건보다 **서로 다른 사유 1건씩**이 매핑을 고치는 데 유용하다. 그리고 이 규칙이 성능을
+ * 지킨다: 그 사유의 표본이 이미 있으면 `JSON.stringify` 를 **아예 하지 않는다.** 실측(레코드 241바이트)
+ * 으로 건당 0.24µs 인데, 초당 1만 건이 전부 거부되면 9,980건은 만들자마자 버려지는 문자열이었다 —
+ * CPU 는 감당되지만 GC 압박이 이벤트 루프로 돌아온다.
+ */
+export declare const SAMPLE_LIMIT = 30;
+/** 표본 하나의 직렬화 상한(문자). */
+export declare const RECORD_MAX = 2000;
+/**
+ * 매핑이 막고 있다고 볼 통과율 문턱.
+ *
+ * 값과 함께 내보낸다 — 화면이 「95% 미만이라 매핑 문제로 봤다」를 말할 수 있게. 숨긴 문턱은 사람이
+ * 판정을 믿지 못한다.
+ */
+export declare const HEALTHY_ACCEPTED_RATIO = 0.95;
+export declare function newIngestLedger(): IngestLedger;
+/**
+ * 창이 다 찼으면 닫아 추이에 넣고 새로 연다. **닫힌 창만 「최근」으로 읽는다.**
+ *
+ * ── 영속이 붙는 유일한 자리 ────────────────────────────────────────────────
+ * 닫힌 창 하나가 영속의 단위다(숫자 넷 + 구간). `onClosed` 를 받는 이유는 **이 함수가 창이 닫히는
+ * 유일한 지점**이기 때문이다 — 여기 한 곳에 붙이면 기록 경로가 갈리지 않는다.
+ *
+ * 왜 건마다가 아니라 창마다인가: 거부마다 행을 쓰면 초당 1만 행이고 그 부하가 이벤트 루프로 돌아온다.
+ * 창마다면 트윈 1,000개에 하루 14.4만 행(약 14MB)이다.
+ *
+ * `onClosed` 는 **오류를 내지 않아야 한다**(호출부가 감싼다) — 영속이 실패해도 장부는 계속 굴러야 한다.
+ * 영속을 지키는 것과 관측을 지키는 것은 다른 일이고, 뒤엣것이 앞엣것 때문에 멈추면 안 된다.
+ */
+export declare function rollIngestWindow(ledger: IngestLedger, nowMs: number, windowMs?: number, onClosed?: (closed: IngestWindow) => void): void;
+/** 사유 묶음의 키. 사유가 여럿이면 한 줄로 잇고, 없으면 지어내지 않고 `unknown`. */
+export declare function reasonKey(errors: string[] | undefined): string;
+/**
+ * 한 번의 인제스트 결과를 적는다.
+ *
+ * `offered` 를 함께 받는 이유: 통과율을 **서로 다른 두 계수기**에서 나눠 계산하면 분모와 분자가 다른
+ * 것을 세게 된다. 둘을 한자리에서 본 수를 그대로 적는다.
+ */
+export declare function recordIngest(ledger: IngestLedger, offered: number, rejected: {
+    record?: unknown;
+    errors?: string[];
+}[] | undefined, nowMs: number, onClosed?: (closed: IngestWindow) => void, 
+/** 매핑은 통과했지만 트윈에 닿지 못한 수 — 「통과」로 세면 화면이 거짓을 말한다. */
+undelivered?: number): void;
+/**
+ * 저널에 **적은 것**을 기록한다 — 창을 넘길 때가 되었으면 넘기고, 행·왕복을 더한다.
+ *
+ * ── 왜 유입과 같은 창인가 ───────────────────────────────────────────────────
+ * 새 장부를 만들지 않는다. 이 창은 「닫힌 창만 최근」·「0 과 없음을 가른다」·「잘린 것을 세어 드러낸다」를
+ * 이미 지키고, 닫힐 때 영속까지 된다. 같은 규율을 두 벌 만들면 한쪽만 고쳐진다.
+ *
+ * ── 유입이 없어도 창은 넘어간다 ────────────────────────────────────────────
+ * 시뮬 트윈은 받는 것 없이 자기가 낸 사실을 적는다. 창이 **유입에서만** 넘어간다면 그 트윈은 추이에
+ * 영원히 나타나지 않는다 — 그래서 쓰기도 창을 넘긴다.
+ */
+export declare function recordJournalWrite(ledger: IngestLedger, rows: number, nowMs: number, onClosed?: (closed: IngestWindow) => void): void;
+/**
+ * 한눈 판정.
+ *
+ * `not-applicable` 과 `not-connected` 를 섞지 않고, 재지 않은 것을 정상·비정상으로 채우지 않는다
+ * (`unknown`). 시뮬 트윈에 「동기화 안 됨」이라 말하면 거짓 경보이고, **거짓 경보는 참 경보를 죽인다.**
+ */
+export type SyncVerdict = 'syncing' /** 유입이 있고 통과율이 문턱 이상 */ | 'mapping-blocked' /** 유입은 있는데 거부가 문턱을 넘는다 — 사유를 보고 매핑을 고친다 */
+/**
+ * 들어오는데 **커널이 받지 않는다** — 사실이 사라지고 있다.
+ *
+ * ── 이름이 사실보다 좁다 (2026-08-20에 드러났다) ────────────────────────────
+ * 관측한 것은 「커널이 받지 않았다」(`ingestLive` 가 0)이고, **멈춘 것은 그 원인 중 하나일 뿐**이다.
+ * 다른 원인이 실제로 있었다: 미러로 선언된 트윈을 사람이 화면에서 시작하면 시뮬 구동으로 떴고, 그
+ * 트윈은 **돌고 있으면서** 유입을 한 건도 받지 못했다. 그때 화면은 한쪽에 「running」, 다른 쪽에
+ * 「멈춰」라고 적었고 사람은 「시작 버튼을 누르면 되겠네」라는 엉뚱한 처방으로 갔다.
+ *
+ * 그래서 **화면 문구는 관측 그대로** 적는다(「트윈에 닿지 않고 버려지는 중」). 이 키 이름은 서버·화면·
+ * 시험에 걸친 계약 문자열이라 그대로 두지만, 이름을 원인으로 읽지 않는다.
+ */
+ | 'twin-not-running' | 'no-traffic' /** 피드는 붙었는데 제시가 0 — 원천·망을 본다 */ | 'not-connected' /** 피드 자체가 없다 — 결선한다 */ | 'not-applicable' /** 원본이 먹이지 않는 트윈(시뮬)·멈춘 트윈 — 물을 대상이 아니다 */ | 'unknown'; /** 한 번도 받지 않았거나 창이 아직 닫히지 않았다 — 기다린다 */
+export declare function syncVerdictOf(args: {
+    /** `live-feed-registry.liveFeedStateOf` 의 답을 그대로 받는다 — 판정 어휘를 두 벌 만들지 않는다. */
+    feedState: 'attached' | 'detached' | 'not-applicable';
+    /** 마지막으로 **닫힌** 창. 없으면 `null`. */
+    recent: {
+        offered: number;
+        rejected: number;
+    } | null;
+    /** 마지막으로 무엇이든 받은 시각. 한 번도 없으면 `-1` — 0 이 아니다(0 은 1970년이다). */
+    lastAtMs?: number;
+    /** 지금. `lastAtMs` 를 견줄 때만 쓴다. */
+    nowMs?: number;
+    /** 마지막으로 **버려진** 시각. 한 번도 없으면 `-1`. */
+    lastUndeliveredAtMs?: number;
+    threshold?: number;
+}): SyncVerdict;
+export interface IngestWindowView {
+    from: string;
+    to: string;
+    offered: number;
+    /** **트윈에 닿은** 수. 제시 − 거부 − 미전달. */
+    accepted: number;
+    /** 매핑이 거부한 수 — 처방은 매핑을 고치는 것. */
+    rejected: number;
+    /** 매핑은 통과했으나 트윈에 닿지 못한 수 — 처방은 트윈을 세우는 것. */
+    undelivered: number;
+    /** 통과율(0~1). 제시가 없으면 `null` — **1 로 채우면 「전부 통과」로 읽힌다.** */
+    acceptedRatio: number | null;
+    /** 이 창에 적힌 행. */
+    rows: number;
+    /** 그것을 적기 위해 DB 를 두드린 횟수 — 행당 왕복이 줄었는지 보는 값. */
+    flushes: number;
+}
+export interface IngestHealthView {
+    verdict: SyncVerdict;
+    /** 판정에 쓴 문턱 — 화면이 왜 그 판정인지 말할 수 있게 함께 낸다. */
+    threshold: number;
+    /** 마지막으로 닫힌 창. 창이 한 번도 닫히지 않았으면 `null`. */
+    recent: IngestWindowView | null;
+    /** 닫힌 창들, 오래된 것부터. */
+    trend: IngestWindowView[];
+    /** 추이 상한에서 밀려난 창 수. */
+    trendDropped: number;
+    /** 누적(기동 이후). */
+    total: {
+        offered: number;
+        accepted: number;
+        rejected: number;
+        undelivered: number;
+        acceptedRatio: number | null;
+        /** 저널에 적힌 행과 그것을 위해 DB 를 두드린 횟수 — 기동 이후 누적. */
+        rows: number;
+        flushes: number;
+    };
+    /** 사유별 누적, 많은 것부터. `lastAt` 이 멈춘 사유는 이미 고쳐진 것이다. */
+    reasons: {
+        reason: string;
+        count: number;
+        lastAt: string;
+    }[];
+    /** 사유 종류가 상한에 닿아 일부가 `(other reasons)` 로 접혔나. */
+    reasonsCapped: boolean;
+    samples: RejectSample[];
+    sampleDropped: number;
+    /** 마지막으로 무엇이든 받은 시각. 한 번도 없으면 `null`. */
+    lastAt: string | null;
+    /** 마지막으로 저널에 적은 시각. 한 번도 없으면 `null` — 받은 적 없는 트윈도 이 값은 있을 수 있다. */
+    lastWriteAt: string | null;
+    /**
+     * **원본에 닿지 못하고 있다** — 없으면 닿고 있다는 뜻이다(§`IngestLedger.readFailure`).
+     *
+     * 「유입 없음」과 **다른 판정**이다: 유입 없음은 원본이 조용한 것일 수 있고, 이것은 우리가 묻지도
+     * 못한 것이다. 화면은 두 문장을 다르게 말해야 한다 — 실 원본이 끊겼을 때 사용자가 원인을 찾을 수
+     * 있는지가 그 차이다.
+     */
+    readFailure?: {
+        consecutive: number;
+        /** 이 단절이 시작된 시각 — 「20분째」를 말할 수 있게. */
+        since: string;
+        lastAt: string;
+        reason: string;
+        stream?: string;
+    };
+}
+/**
+ * 읽기용 요약.
+ *
+ * 장부가 없어도(한 번도 받지 않은 트윈) **판정은 낸다** — 피드 사실만으로 답할 수 있는 경우가 있다
+ * (`not-applicable`·`not-connected`). 그 경우 수치는 비운다: 없는 값을 0 으로 채우지 않는다.
+ *
+ * `nowMs` 를 받는 이유: 끊긴 피드를 가려내려면 「마지막 유입이 얼마나 전인가」를 봐야 하고, 그 판단을
+ * 화면이 아니라 여기서 한다(소비처마다 다시 판단하면 규칙이 갈라진다). 시험이 시각을 고정할 수 있도록
+ * 인자로 받는다.
+ */
+export declare function ingestHealth(ledger: IngestLedger | undefined, feedState: 'attached' | 'detached' | 'not-applicable', threshold?: number, nowMs?: number): IngestHealthView;