@operato/twin-kernel 0.7.63 → 0.7.65

package/dist/contract.d.ts

@@ -5,6 +5,31 @@ export interface CanonicalEnvelope<T = unknown> {
     eventTime: ISOTime;
     tenantId: string;
     correlationId?: string;
+    /**
+     * **사람이 그때 적어 둔 말** — 연결된 시스템에서 온 자유 문장.
+     *
+     * ── 왜 이 자리가 필요한가 (2026-08-25) ────────────────────────────────────
+     * 재고 조정만은 **원인이 트윈의 모델 밖에 있다.** 다른 이동은 원인을 트윈이 스스로 압니다 —
+     * 꺼내 간 것은 작업 지시가 시켰고, 적치는 입고가 시켰습니다. 그런데 조정은 **사람이 판단한 것**이고,
+     * 그 이유는 그 사람이 적은 문장에만 있습니다(「실재고로 조정(192kg→198kg)」).
+     *
+     * 그 문장이 없으면 트윈은 「6kg 이 늘었다」까지만 알고 **왜인지 영원히 답하지 못합니다.**
+     *
+     * ── 왜 봉투에 두고 상태에 두지 않나 ──────────────────────────────────────
+     * 그 문장은 **지난 사건에 대한 사실**이고 지금 수량에 대한 사실이 아닙니다. 상태에 두면 조정 열 번에
+     * 문장 열 개가 쌓여 시간에 비례해 자랍니다. 지난 기록이 답하는 물음입니다.
+     *
+     * 그리고 EPCIS 사건 안에 넣지 않습니다 — 표준에 그 칸이 없고, 이름을 지어 넣으면 그 사건이
+     * 표준을 벗어납니다. 봉투는 우리 것이므로 여기가 맞고, 지난 기록에는 봉투가 그대로 남습니다.
+     *
+     * ── 커널은 읽지 않습니다 ─────────────────────────────────────────────────
+     * 자유 문장이므로 어떤 판단에도 쓰지 않습니다. 나르기만 합니다. 비어 있으면 이 칸을 만들지
+     * 않습니다 — 빈 문장은 「적지 않았다」와 다르게 보입니다.
+     *
+     * 표준 근거: ISA-95 가 거의 모든 타입에 두는 `Description`(DescriptionType). 사람의 글을 담는
+     * 표준 자리이고, EPCIS 핵심에는 없어 확장으로 갑니다.
+     */
+    description?: string;
     data: T;
 }
 /**

package/dist/face2-adapter.d.ts

@@ -2,6 +2,34 @@ import type { CanonicalEnvelope } from './contract.ts';
 import type { EpcisEvent } from './epcis.ts';
 /** 매핑 값: 리터럴, 또는 소스 필드 참조("$.field.path"). */
 export type MapValue = string;
+/**
+ * **정정 선언 매핑** — 「이 사건은 없던 일이 되었다」를 표준 어휘로 옮기는 자리.
+ *
+ * ── 왜 뒤늦게 생겼나 (2026-08-25) ───────────────────────────────────────────
+ * `quantityList` · `ilmd` 와 **똑같은 모양의 결함**이었다. 받는 쪽은 처음부터 다 있었다 —
+ * 타입(`ErrorDeclaration`) · 검증(선언 시각·정정 대상 검사) · 리듀서(정정 목록에 적고 상태는
+ * 흔들지 않는다). 옮길 자리만 없었다.
+ *
+ * 실 시스템은 잘못 보낸 것을 정정한다. 그 정정을 실을 자리가 없으면 두 길뿐인데 둘 다 나쁘다:
+ * 취소를 **새 사실**로 보내 재고를 두 번 흔들거나, 아예 보내지 않아 지난 기록이 일어나지 않은 일을
+ * 일어난 것으로 계속 말하게 한다. 표준이 세 번째 길을 정해 두었다 — 앞선 사건을 지우지 않고
+ * 「정정되었다」를 함께 남긴다(EPCIS 2.0 §7.5).
+ *
+ * **세 값은 함께여야 뜻이 있다.** 그래서 평평한 세 필드가 아니라 묶음 하나로 둔다 — 반쯤 채운
+ * 정정 선언은 정정이 아니다.
+ *
+ * 이유(`reason`)는 CBV 어휘다(`did_not_occur` · `incorrect_data`). 연결된 시스템의 낱말
+ * (`UNDO_UNLOADING` 같은 것)을 그 둘 중 하나로 옮기는 것은 커넥터의 일이다 — 여기서 그 번역을
+ * 대신하면 시스템마다 다른 규칙이 이 파일에 쌓인다.
+ */
+export interface ErrorDeclarationMapping {
+    /** 정정을 **선언한** 시각. 사건이 일어난 시각이 아니다 — 없으면 지어내지 않고 이유와 함께 알린다. */
+    declarationTime: MapValue;
+    /** CBV 이유 어휘. 연결된 시스템이 이유를 말하지 않으면 비워 둔다(둘 중 하나로 짐작하지 않는다). */
+    reason?: MapValue;
+    /** 정정이 가리키는 원래 사건들의 `eventID`("$.correctiveEventIDs") — 문자열 배열. */
+    correctiveEventIDs?: MapValue;
+}
 /** ObjectEvent 매핑 스펙(선언적). */
 export interface ObjectEventMapping {
     type: 'ObjectEvent';
@@ -47,6 +75,8 @@ export interface ObjectEventMapping {
     ilmd?: MapValue;
     readPoint?: MapValue;
     bizLocation?: MapValue;
+    /** 이 레코드가 앞선 사건의 정정이면 그 선언(§ErrorDeclarationMapping). */
+    errorDeclaration?: ErrorDeclarationMapping;
 }
 /**
  * AggregationEvent 매핑 스펙 — **담김의 사실**(무엇이 무엇에 실렸나).
@@ -74,6 +104,8 @@ export interface AggregationEventMapping {
     childQuantityList?: MapValue;
     readPoint?: MapValue;
     bizLocation?: MapValue;
+    /** 이 레코드가 앞선 사건의 정정이면 그 선언(§ErrorDeclarationMapping). */
+    errorDeclaration?: ErrorDeclarationMapping;
 }
 /**
  * **변환의 사실** — 무엇이 들어가 무엇이 나왔나(EPCIS `TransformationEvent`).
@@ -104,6 +136,8 @@ export interface TransformationEventMapping {
     transformationID?: MapValue;
     readPoint?: MapValue;
     bizLocation?: MapValue;
+    /** 이 레코드가 앞선 사건의 정정이면 그 선언(§ErrorDeclarationMapping). */
+    errorDeclaration?: ErrorDeclarationMapping;
 }
 export type EventMapping = ObjectEventMapping | AggregationEventMapping | TransformationEventMapping;
 /**
@@ -143,7 +177,6 @@ export interface IngestResult {
     }[];
 }
 type Rec = Record<string, unknown>;
-/** 단일 레코드 → 정규 EPCIS 이벤트 + 매핑에서 드러난 문제(검증은 `ingest` 가 이어서 한다). */
 export declare function mapRecordChecked(record: Rec, mapping: EventMapping, eventTime: string): {
     event: EpcisEvent;
     errors: string[];

package/dist/face2-adapter.js

@@ -120,12 +120,49 @@ function resolveObject(v, record, field, errors) {
     return Object.keys(o).length ? o : undefined;
 }
 /** 단일 레코드 → 정규 EPCIS 이벤트 + 매핑에서 드러난 문제(검증은 `ingest` 가 이어서 한다). */
+/**
+ * 정정 선언 묶음 → 표준 `ErrorDeclaration`.
+ *
+ * 선언 시각이 없으면 **이유와 함께 알리고 붙이지 않는다.** 사건 시각으로 메우고 싶어지는 자리인데,
+ * 그러면 「언제 정정했나」가 「언제 일어났나」와 같아져 둘을 다시 갈라낼 방법이 없다.
+ */
+function resolveErrorDeclaration(spec, record, errors) {
+    if (!spec)
+        return undefined;
+    const declarationTime = resolve(spec.declarationTime, record, 'errorDeclaration.declarationTime', errors);
+    const reason = resolve(spec.reason, record, 'errorDeclaration.reason', errors);
+    const correctiveEventIDs = resolveList(spec.correctiveEventIDs, record, 'errorDeclaration.correctiveEventIDs', errors);
+    /*
+     * ★ **자리가 있다는 것과 정정이라는 것은 다르다.**
+     *
+     * 매핑은 한 번 적고 모든 레코드가 그것을 지난다. 정정은 드문 사건이므로 **거의 모든 레코드에는 이
+     * 세 값이 없다.** 그때 오류를 내면 평범한 관측 전부가 매핑 오류를 달게 되고, 라이브가 통째로
+     * 막힌다 — 자리를 낸 것이 곧 통로를 막는 일이 된다.
+     *
+     * 그래서 아무 말도 없으면 정정이 아닌 것이다. **반쯤 말한 것**만 오류다: 이유나 정정 대상은 있는데
+     * 선언 시각이 없으면 정정하려던 것이 분명한데 언제인지 모르는 것이고, 그 시각은 지어낼 수 없다.
+     */
+    if (!declarationTime) {
+        if (reason || correctiveEventIDs.length) {
+            errors.push('errorDeclaration 이 반쯤 왔다 — 이유·정정 대상은 있는데 declarationTime 이 없다(정정 시각은 지어낼 수 없다)');
+        }
+        return undefined;
+    }
+    return {
+        declarationTime,
+        ...(reason ? { reason } : {}),
+        ...(correctiveEventIDs.length ? { correctiveEventIDs } : {})
+    };
+}
 export function mapRecordChecked(record, mapping, eventTime) {
     const errors = [];
     const bizStep = resolve(mapping.bizStep, record, 'bizStep', errors) ?? '';
     const disposition = resolve(mapping.disposition, record, 'disposition', errors);
     const readPoint = resolve(mapping.readPoint, record, 'readPoint', errors);
     const bizLocation = resolve(mapping.bizLocation, record, 'bizLocation', errors);
+    /* 정정 선언은 표준 **헤더**의 것이므로 세 종류 모두에 담긴다(§7.5). 한 종류에만 내면 같은 결함이
+       나머지 둘에 남는다 — 그것을 이미 두 번 겪었다(`quantityList` · `ilmd`). */
+    const errorDeclaration = resolveErrorDeclaration(mapping.errorDeclaration, record, errors);
     if (mapping.type === 'TransformationEvent') {
         const inputEPCList = resolveList(mapping.inputEPCList, record, 'inputEPCList', errors);
         const inputQuantityList = resolveQuantityList(mapping.inputQuantityList, record, 'inputQuantityList', errors);
@@ -156,6 +193,7 @@ export function mapRecordChecked(record, mapping, eventTime) {
                 ...(outputEPCList.length ? { outputEPCList } : {}),
                 ...(outputQuantityList.length ? { outputQuantityList } : {}),
                 ...(transformationID ? { transformationID } : {}),
+                ...(errorDeclaration ? { errorDeclaration } : {}),
                 readPoint, bizLocation
             }),
             errors
@@ -172,6 +210,7 @@ export function mapRecordChecked(record, mapping, eventTime) {
                 /* 없는 쪽은 **필드를 만들지 않는다** — 빈 배열을 실으면 「자식이 없다」고 말하는 것이 된다. */
                 ...(childEPCs.length ? { childEPCs } : {}),
                 ...(childQuantityList.length ? { childQuantityList } : {}),
+                ...(errorDeclaration ? { errorDeclaration } : {}),
                 readPoint, bizLocation
             }),
             errors
@@ -192,6 +231,7 @@ export function mapRecordChecked(record, mapping, eventTime) {
             epcList: epc ? [epc] : [],
             ...(quantityList.length ? { quantityList } : {}),
             ...(ilmd ? { ilmd } : {}),
+            ...(errorDeclaration ? { errorDeclaration } : {}),
             readPoint, bizLocation
         }),
         errors
@@ -225,11 +265,18 @@ export function ingest(records, rules, opts) {
             rejected.push({ record, errors });
             continue;
         }
+        /*
+         * 사람이 적어 둔 말은 **봉투에** 싣는다(§`CanonicalEnvelope.description`) — EPCIS 사건 안에 넣으면
+         * 그 사건이 표준을 벗어난다. 지난 기록에는 봉투가 그대로 남으므로 잃지 않는다.
+         * 비어 있으면 이 칸을 만들지 않는다 — 빈 문장은 「적지 않았다」와 다르게 보인다.
+         */
+        const note = typeof record['description'] === 'string' ? String(record['description']).trim() : '';
         accepted.push({
             eventId: `${opts.tenantId}-ingest-${++seq}`,
             eventType: `epcis.${ev.type}`,
             eventTime: ev.eventTime,
             tenantId: opts.tenantId,
+            ...(note ? { description: note } : {}),
             data: ev
         });
     }

package/dist/flow-engine.d.ts

@@ -365,6 +365,15 @@ export declare function deriveAttentions(view: {
         goodCount?: number;
         scrapCount?: number;
         offShift?: boolean;
+        /**
+         * 이 설비 소식이 끊긴 시간, 그리고 그때까지 가장 오래 끊겼던 시간(밀리초).
+         * 실제 현장을 따라가는 트윈만 이 값을 넣는다.
+         *
+         * 값이 없으면 이 항목은 판단하지 않는다. 스스로 상태를 만들어 가는 트윈에는 소식이 끊긴다는
+         * 것이 없으므로 값을 넣지 않는다(`tasks` · `now` 도 같은 방식이다).
+         */
+        silentMs?: number;
+        longestSilenceBeforeMs?: number;
     }[];
     locations: {
         id: string;

package/dist/flow-engine.js

@@ -106,6 +106,43 @@ thresholds) {
                 suggestedAction: { code: 'act.repair', command: CMD.resourceRepair, args: { resourceId: m.id } }
             });
         }
+        /*
+         * 이 설비 소식이 지난 간격보다 오래 끊겼다는 신호. 설비가 멈췄다는 뜻이 아니고, 지금 상태를 우리가
+         * 모르고 있다는 뜻이다.
+         *
+         * ── 왜 필요한가 ───────────────────────────────────────────────────────────
+         * 연결된 시스템에서 값이 오다가 끊기는 일은 흔하다(통신 두절, 야간 정지, 커넥터 중단). 그때
+         * 트윈은 마지막으로 받은 값을 그대로 들고 있고, 화면은 그 값을 지금 상태로 그린다. 어제 오후에
+         * 받은 「가동 중」이 오늘 아침에도 「가동 중」으로 보인다. 오류가 나지 않으므로 아무도 확인하지
+         * 않는다. 값이 비어 있으면 사람이 의심하지만, 오래된 값이 채워져 있으면 의심하지 않는다.
+         *
+         * ── 왜 상태 필드가 아니라 신호인가 ────────────────────────────────────────
+         * 「가동 중」은 설비의 상태이고, 「그 값을 언제 받았나」는 우리 쪽 사정이다. 두 가지를 한 필드에
+         * 담으면 화면과 집계가 구별할 수 없다. 물품 쪽에서 같은 이유로 `seenAtMs` 를 상태에서 뺐다.
+         *
+         * ── 판단 기준을 우리가 정하지 않는다 ──────────────────────────────────────
+         * 「몇 분 넘게 값이 없으면 이상하다」는 현장마다 다르다. 1초마다 값을 보내는 계측기와 하루 한 번
+         * 올라오는 점검 기록이 같은 표에 있다. 기준을 하나로 정하면 앞쪽에는 신호가 너무 많이 서고
+         * 뒤쪽에는 서지 않는다. 그래서 그 설비가 지금까지 보여 준 가장 긴 간격을 기준으로 쓴다.
+         *
+         * 지난 간격을 아직 모르는 설비는 신호를 내지 않는다. 조치도 붙이지 않는다 — 고쳐야 할 것이
+         * 설비인지 연결인지 우리가 알 수 없다.
+         */
+        if (m.silentMs !== undefined && m.longestSilenceBeforeMs !== undefined && m.silentMs > m.longestSilenceBeforeMs) {
+            out.push({
+                id: `silent:${m.id}`,
+                kind: 'equipment-silent',
+                severity: 'medium',
+                anchor: { moverId: m.id, locationId: m.location },
+                params: {
+                    moverId: m.id,
+                    ...(m.location ? { locationId: m.location } : {}),
+                    silentMs: m.silentMs,
+                    longestBeforeMs: m.longestSilenceBeforeMs,
+                    ...(m.status ? { lastStatus: m.status } : {})
+                }
+            });
+        }
     }
     for (const n of view.locations) {
         /*
@@ -1773,8 +1810,21 @@ export class FlowEngine {
                     criteriaOf.set(n.id, cs);
             }
         }
+        /*
+         * 소식이 끊긴 시간은 상태에 없고 받은 기록에만 있으므로 리듀서에게 묻는다. 스스로 상태를 만들어
+         * 가는 트윈에는 그 리듀서가 없고, 그때는 값을 넣지 않으므로 이 신호도 서지 않는다.
+         *
+         * 앞날을 계산하는 사본(`fork`)에서도 묻지 않는다. 사본은 `structuredClone` 으로 만들어서 리듀서가
+         * 메서드 없는 객체가 되고(§`ItemStore.clone`), 그대로 부르면 오류가 난다. 실제로 테스트 네 건이
+         * 그렇게 실패했다. 다만 결과는 맞다 — 앞날 계산은 자기 시계로 진행하므로 소식이 끊긴다는 것이
+         * 없다. 소식이 끊긴 사실은 현장을 따라가는 트윈이 알리고, 앞날 계산은 그 뒤의 일이다.
+         */
+        const silence = typeof this.observer?.equipmentSilence === 'function' ? this.observer.equipmentSilence() : undefined;
         const out = deriveAttentions({
-            equipment: [...this.equipment.values()],
+            equipment: [...this.equipment.values()].map(m => {
+                const s = silence?.get(m.id);
+                return s ? { ...m, silentMs: s.silentMs, longestSilenceBeforeMs: s.longestBeforeMs } : m;
+            }),
             locations: [...this.locations.values()].map(n => {
                 const criteria = criteriaOf.get(n.id);
                 return criteria?.length ? { ...n, criteria } : n;

package/dist/observed-reducer.d.ts

@@ -156,12 +156,35 @@ export interface ReducerCheckpoint {
         id: string;
         values: LocationObservation[];
     }[];
+    /**
+     * 설비마다 두 값 — 마지막으로 값을 받은 시각, 그리고 그때까지 값이 가장 오래 끊겼던 길이.
+     * §`equipmentSilence` 가 이 값으로 판단한다.
+     *
+     * 저장해 두어야 한다. 저장하지 않으면 재기동한 뒤에 값이 얼마나 끊겼는지 계산할 수 없다.
+     * 그러면 화면은 어제 받은 상태를 오늘의 상태로 그린다.
+     */
+    heard?: {
+        id: string;
+        atMs: number;
+        longestGapMs?: number;
+    }[];
 }
 export declare class ObservedReducer {
     /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
     private master;
     /** 자리별 · 속성별 **마지막 관측** — 이력이 아니다(§`OP_EVENT.observation`). */
     private observations;
+    /**
+     * 설비별 **마지막으로 들은 시각** — 그 설비의 상태가 아니라 **우리 지식의 상태**다.
+     *
+     * ── 왜 상태에 넣지 않나 ─────────────────────────────────────────────────────
+     * 「가동 중」은 설비에 대한 사실이고 「그 말을 언제 들었나」는 우리에 대한 사실이다. 상태에 섞으면
+     * 두 종류가 한 통에 담기고, 자체 구동(시뮬)에는 없는 값이라 두 구동이 어긋난다 — 물품의
+     * `seenAtMs` 가 같은 이유로 상태에서 빠졌다(§`snapshot`).
+     *
+     * 그래서 여기 안에 두고, 밖으로는 **주의 신호**로만 낸다(§`equipmentSilence`).
+     */
+    private heard;
     private items;
     private aggregation;
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
@@ -250,6 +273,29 @@ export declare class ObservedReducer {
      * 겹칠 때의 보조 기준이다. 시각이 없으면 판정하지 않는다(있는 것만 가지고 판단한다).
      */
     private stale;
+    /**
+     * 이 설비의 값을 받은 시각을 적고, 지난번 값과의 간격 중 가장 긴 것을 함께 기록한다.
+     *
+     * 간격을 기록하는 이유는 판단 기준을 우리가 정하지 않기 위해서다. 「몇 분 넘게 소식이 없으면
+     * 이상하다」는 현장마다 다르다 — 1초마다 값을 보내는 계측기와 하루 한 번 올라오는 점검 기록이
+     * 같은 표에 있다. 기준을 하나로 정하면 앞쪽에는 신호가 너무 많이 서고 뒤쪽에는 서지 않는다.
+     * 그래서 그 설비가 지금까지 실제로 보여 준 간격을 기준으로 쓴다.
+     */
+    private markHeard;
+    /**
+     * 값이 지난 간격보다 오래 끊긴 설비의 목록. 밖으로 내보내는 값은 이것 하나다.
+     *
+     * 끊긴 시간은 이 트윈이 마지막으로 어떤 값이든 받은 시각을 기준으로 잰다. 연결이 통째로 멈추면 그
+     * 기준도 멈추므로 아무 신호도 서지 않는다. 그때 알려야 할 사실은 설비마다의 상태가 아니라 「연결이
+     * 끊겼다」 하나이고, 그것은 유입 장부가 알린다.
+     *
+     * 지난 간격을 아직 모르는 설비는 목록에 넣지 않는다. 값을 한 번만 받았다면 이 설비가 원래 얼마나
+     * 뜸하게 보내는지 알 수 없다.
+     */
+    equipmentSilence(): Map<string, {
+        silentMs: number;
+        longestBeforeMs: number;
+    }>;
     /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
     private lastAt;
     /**

package/dist/observed-reducer.js

@@ -43,6 +43,17 @@ export class ObservedReducer {
     master = new Map();
     /** 자리별 · 속성별 **마지막 관측** — 이력이 아니다(§`OP_EVENT.observation`). */
     observations = new Map();
+    /**
+     * 설비별 **마지막으로 들은 시각** — 그 설비의 상태가 아니라 **우리 지식의 상태**다.
+     *
+     * ── 왜 상태에 넣지 않나 ─────────────────────────────────────────────────────
+     * 「가동 중」은 설비에 대한 사실이고 「그 말을 언제 들었나」는 우리에 대한 사실이다. 상태에 섞으면
+     * 두 종류가 한 통에 담기고, 자체 구동(시뮬)에는 없는 값이라 두 구동이 어긋난다 — 물품의
+     * `seenAtMs` 가 같은 이유로 상태에서 빠졌다(§`snapshot`).
+     *
+     * 그래서 여기 안에 두고, 밖으로는 **주의 신호**로만 낸다(§`equipmentSilence`).
+     */
+    heard = new Map();
     items = new Map();
     aggregation = new Map();
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
@@ -245,6 +256,54 @@ export class ObservedReducer {
         this.lastAt.set(key, { at, recorded: Number.isFinite(recorded) ? recorded : seen.recorded });
         return false;
     }
+    /**
+     * 이 설비의 값을 받은 시각을 적고, 지난번 값과의 간격 중 가장 긴 것을 함께 기록한다.
+     *
+     * 간격을 기록하는 이유는 판단 기준을 우리가 정하지 않기 위해서다. 「몇 분 넘게 소식이 없으면
+     * 이상하다」는 현장마다 다르다 — 1초마다 값을 보내는 계측기와 하루 한 번 올라오는 점검 기록이
+     * 같은 표에 있다. 기준을 하나로 정하면 앞쪽에는 신호가 너무 많이 서고 뒤쪽에는 서지 않는다.
+     * 그래서 그 설비가 지금까지 실제로 보여 준 간격을 기준으로 쓴다.
+     */
+    markHeard(id, e) {
+        const at = Date.parse(String(e.eventTime ?? ''));
+        if (!Number.isFinite(at))
+            return;
+        const prev = this.heard.get(id);
+        if (!prev) {
+            this.heard.set(id, { atMs: at });
+            return;
+        }
+        /* 이미 지난 시각이 담긴 사건은 간격 계산에서 뺀다. 도착이 늦은 사건이고, 값이 끊긴 것이 아니다. */
+        if (at <= prev.atMs)
+            return;
+        const gap = at - prev.atMs;
+        this.heard.set(id, { atMs: at, longestGapMs: Math.max(prev.longestGapMs ?? 0, gap) });
+    }
+    /**
+     * 값이 지난 간격보다 오래 끊긴 설비의 목록. 밖으로 내보내는 값은 이것 하나다.
+     *
+     * 끊긴 시간은 이 트윈이 마지막으로 어떤 값이든 받은 시각을 기준으로 잰다. 연결이 통째로 멈추면 그
+     * 기준도 멈추므로 아무 신호도 서지 않는다. 그때 알려야 할 사실은 설비마다의 상태가 아니라 「연결이
+     * 끊겼다」 하나이고, 그것은 유입 장부가 알린다.
+     *
+     * 지난 간격을 아직 모르는 설비는 목록에 넣지 않는다. 값을 한 번만 받았다면 이 설비가 원래 얼마나
+     * 뜸하게 보내는지 알 수 없다.
+     */
+    equipmentSilence() {
+        const out = new Map();
+        const now = this.observedAtMs;
+        if (now === undefined)
+            return out;
+        for (const [id, h] of this.heard) {
+            if (h.longestGapMs === undefined)
+                continue;
+            const silentMs = now - h.atMs;
+            if (silentMs <= 0)
+                continue;
+            out.set(id, { silentMs, longestBeforeMs: h.longestGapMs });
+        }
+        return out;
+    }
     /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
     lastAt = new Map();
     /**
@@ -333,6 +392,7 @@ export class ObservedReducer {
                 /* 유효 기간은 **마스터 사실**이므로 침묵을 "없어졌다" 로 읽지 않고 아는 값을 지킨다.
                    판정은 여기서 하지 않는다 — `snapshot()` 이 관측 시각으로 `effectivityAt` 을 부른다. */
                 const eqPeriod = d.effectiveStart || d.effectiveEnd ? effectiveOf(d) : effectiveOf(known);
+                this.markHeard(d.moverId, e);
                 this.equipment.set(d.moverId, { id: d.moverId, kind: d.kind, status: d.status, location: d.location, ...(homeLocation ? { homeLocation } : {}), taskId: d.taskId, motion: d.motion, origin: known?.origin ?? 'observed', ...eqPeriod, ...(d.held ? { held: true } : {}) });
                 break;
             }
@@ -963,7 +1023,9 @@ export class ObservedReducer {
             orders: [...this.orders.values()].map(o => ({ ...o })),
             acked: [...this.acked],
             corrections: this.corrections.map(c => ({ ...c })),
-            unhandled: [...this.unhandled.entries()].map(([eventType, v]) => ({ eventType, ...v }))
+            unhandled: [...this.unhandled.entries()].map(([eventType, v]) => ({ eventType, ...v })),
+            /* 마지막으로 들은 시각 — 이어받지 않으면 재기동 뒤에 침묵의 길이를 말할 수 없다. */
+            heard: [...this.heard.entries()].map(([id, v]) => ({ id, ...v }))
         };
     }
     /**
@@ -975,6 +1037,7 @@ export class ObservedReducer {
         this.observations = new Map((cp?.observations ?? []).map(o => [o.id, new Map((o.values ?? []).map(v => [v.propertyId, { ...v }]))]));
         this.revision = cp?.revision ?? 0;
         this.master = new Map((cp?.master ?? []).map(n => [n.id, { ...n }]));
+        this.heard = new Map((cp?.heard ?? []).map(h => [h.id, { atMs: h.atMs, ...(h.longestGapMs !== undefined ? { longestGapMs: h.longestGapMs } : {}) }]));
         this.items = new Map((cp?.items ?? []).map(i => [i.epc, { ...i }]));
         this.aggregation = new Map((cp?.aggregation ?? []).map(a => [a.parent, [...a.children]]));
         this.pendingParent = new Map((cp?.pendingParent ?? []).map(x => [x.child, x.parent]));

package/dist/operational-ingest.js

@@ -267,8 +267,15 @@ export function ingestOperationalRecords(records, opts) {
         const spec = SPECS[kind];
         const r = record;
         const errors = [];
-        /* 모르는 이름은 거부한다 — 한 글자 틀린 필드가 조용히 사라지는 것을 막는다. */
-        const unknown = Object.keys(r).filter(k => k !== 'at' && spec.fields[k] === undefined);
+        /*
+         * 모르는 이름은 거부한다 — 한 글자 틀린 필드가 오류 없이 사라지는 것을 막는다.
+         *
+         * 둘은 뺀다. **사실의 칸이 아니라 봉투의 칸**이다: `at` 은 그 사실이 일어난 시각이고,
+         * `description` 은 사람이 그때 적어 둔 말이다(§`CanonicalEnvelope.description`). 사실 칸으로
+         * 검사하면 명세마다 같은 두 줄을 적어야 하고, 한 곳을 빠뜨리면 그 통로만 거부한다.
+         */
+        const ENVELOPE_FIELDS = ['at', 'description'];
+        const unknown = Object.keys(r).filter(k => !ENVELOPE_FIELDS.includes(k) && spec.fields[k] === undefined);
         if (unknown.length)
             errors.push(`${kind}: 계약에 없는 필드 — ${unknown.join(', ')}`);
         for (const name of spec.required) {
@@ -357,11 +364,14 @@ export function ingestOperationalRecords(records, opts) {
             rejected.push({ record, errors });
             continue;
         }
+        /* 사람이 적어 둔 말 — 봉투에 싣는다(§`CanonicalEnvelope.description`). 물류 쪽과 같은 자리다. */
+        const note = typeof r.description === 'string' ? String(r.description).trim() : '';
         accepted.push({
             eventId: `${opts.tenantId}-op-${kind}-${++seq}`,
             eventType: spec.eventType,
             eventTime: new Date(atMs).toISOString(),
             tenantId: opts.tenantId,
+            ...(note ? { description: note } : {}),
             data
         });
     }

package/dist-cjs/index.cjs

@@ -1389,6 +1389,17 @@ var ObservedReducer = class {
   master = /* @__PURE__ */ new Map();
   /** 자리별 · 속성별 **마지막 관측** — 이력이 아니다(§`OP_EVENT.observation`). */
   observations = /* @__PURE__ */ new Map();
+  /**
+   * 설비별 **마지막으로 들은 시각** — 그 설비의 상태가 아니라 **우리 지식의 상태**다.
+   *
+   * ── 왜 상태에 넣지 않나 ─────────────────────────────────────────────────────
+   * 「가동 중」은 설비에 대한 사실이고 「그 말을 언제 들었나」는 우리에 대한 사실이다. 상태에 섞으면
+   * 두 종류가 한 통에 담기고, 자체 구동(시뮬)에는 없는 값이라 두 구동이 어긋난다 — 물품의
+   * `seenAtMs` 가 같은 이유로 상태에서 빠졌다(§`snapshot`).
+   *
+   * 그래서 여기 안에 두고, 밖으로는 **주의 신호**로만 낸다(§`equipmentSilence`).
+   */
+  heard = /* @__PURE__ */ new Map();
   items = /* @__PURE__ */ new Map();
   aggregation = /* @__PURE__ */ new Map();
   /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
@@ -1566,6 +1577,48 @@ var ObservedReducer = class {
     this.lastAt.set(key, { at, recorded: Number.isFinite(recorded) ? recorded : seen.recorded });
     return false;
   }
+  /**
+   * 이 설비의 값을 받은 시각을 적고, 지난번 값과의 간격 중 가장 긴 것을 함께 기록한다.
+   *
+   * 간격을 기록하는 이유는 판단 기준을 우리가 정하지 않기 위해서다. 「몇 분 넘게 소식이 없으면
+   * 이상하다」는 현장마다 다르다 — 1초마다 값을 보내는 계측기와 하루 한 번 올라오는 점검 기록이
+   * 같은 표에 있다. 기준을 하나로 정하면 앞쪽에는 신호가 너무 많이 서고 뒤쪽에는 서지 않는다.
+   * 그래서 그 설비가 지금까지 실제로 보여 준 간격을 기준으로 쓴다.
+   */
+  markHeard(id, e) {
+    const at = Date.parse(String(e.eventTime ?? ""));
+    if (!Number.isFinite(at)) return;
+    const prev = this.heard.get(id);
+    if (!prev) {
+      this.heard.set(id, { atMs: at });
+      return;
+    }
+    if (at <= prev.atMs) return;
+    const gap = at - prev.atMs;
+    this.heard.set(id, { atMs: at, longestGapMs: Math.max(prev.longestGapMs ?? 0, gap) });
+  }
+  /**
+   * 값이 지난 간격보다 오래 끊긴 설비의 목록. 밖으로 내보내는 값은 이것 하나다.
+   *
+   * 끊긴 시간은 이 트윈이 마지막으로 어떤 값이든 받은 시각을 기준으로 잰다. 연결이 통째로 멈추면 그
+   * 기준도 멈추므로 아무 신호도 서지 않는다. 그때 알려야 할 사실은 설비마다의 상태가 아니라 「연결이
+   * 끊겼다」 하나이고, 그것은 유입 장부가 알린다.
+   *
+   * 지난 간격을 아직 모르는 설비는 목록에 넣지 않는다. 값을 한 번만 받았다면 이 설비가 원래 얼마나
+   * 뜸하게 보내는지 알 수 없다.
+   */
+  equipmentSilence() {
+    const out = /* @__PURE__ */ new Map();
+    const now = this.observedAtMs;
+    if (now === void 0) return out;
+    for (const [id, h] of this.heard) {
+      if (h.longestGapMs === void 0) continue;
+      const silentMs = now - h.atMs;
+      if (silentMs <= 0) continue;
+      out.set(id, { silentMs, longestBeforeMs: h.longestGapMs });
+    }
+    return out;
+  }
   /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
   lastAt = /* @__PURE__ */ new Map();
   /**
@@ -1624,6 +1677,7 @@ var ObservedReducer = class {
         const known = this.equipment.get(d.moverId);
         const homeLocation = d.homeLocation ?? known?.homeLocation;
         const eqPeriod = d.effectiveStart || d.effectiveEnd ? effectiveOf(d) : effectiveOf(known);
+        this.markHeard(d.moverId, e);
         this.equipment.set(d.moverId, { id: d.moverId, kind: d.kind, status: d.status, location: d.location, ...homeLocation ? { homeLocation } : {}, taskId: d.taskId, motion: d.motion, origin: known?.origin ?? "observed", ...eqPeriod, ...d.held ? { held: true } : {} });
         break;
       }
@@ -2063,7 +2117,9 @@ var ObservedReducer = class {
       orders: [...this.orders.values()].map((o) => ({ ...o })),
       acked: [...this.acked],
       corrections: this.corrections.map((c) => ({ ...c })),
-      unhandled: [...this.unhandled.entries()].map(([eventType, v]) => ({ eventType, ...v }))
+      unhandled: [...this.unhandled.entries()].map(([eventType, v]) => ({ eventType, ...v })),
+      /* 마지막으로 들은 시각 — 이어받지 않으면 재기동 뒤에 침묵의 길이를 말할 수 없다. */
+      heard: [...this.heard.entries()].map(([id, v]) => ({ id, ...v }))
     };
   }
   /**
@@ -2077,6 +2133,7 @@ var ObservedReducer = class {
     );
     this.revision = cp?.revision ?? 0;
     this.master = new Map((cp?.master ?? []).map((n) => [n.id, { ...n }]));
+    this.heard = new Map((cp?.heard ?? []).map((h) => [h.id, { atMs: h.atMs, ...h.longestGapMs !== void 0 ? { longestGapMs: h.longestGapMs } : {} }]));
     this.items = new Map((cp?.items ?? []).map((i) => [i.epc, { ...i }]));
     this.aggregation = new Map((cp?.aggregation ?? []).map((a) => [a.parent, [...a.children]]));
     this.pendingParent = new Map((cp?.pendingParent ?? []).map((x) => [x.child, x.parent]));
@@ -3276,12 +3333,30 @@ function resolveObject(v, record, field, errors) {
   const o = { ...r };
   return Object.keys(o).length ? o : void 0;
 }
+function resolveErrorDeclaration(spec, record, errors) {
+  if (!spec) return void 0;
+  const declarationTime = resolve(spec.declarationTime, record, "errorDeclaration.declarationTime", errors);
+  const reason = resolve(spec.reason, record, "errorDeclaration.reason", errors);
+  const correctiveEventIDs = resolveList(spec.correctiveEventIDs, record, "errorDeclaration.correctiveEventIDs", errors);
+  if (!declarationTime) {
+    if (reason || correctiveEventIDs.length) {
+      errors.push("errorDeclaration \uC774 \uBC18\uCBE4 \uC654\uB2E4 \u2014 \uC774\uC720\xB7\uC815\uC815 \uB300\uC0C1\uC740 \uC788\uB294\uB370 declarationTime \uC774 \uC5C6\uB2E4(\uC815\uC815 \uC2DC\uAC01\uC740 \uC9C0\uC5B4\uB0BC \uC218 \uC5C6\uB2E4)");
+    }
+    return void 0;
+  }
+  return {
+    declarationTime,
+    ...reason ? { reason } : {},
+    ...correctiveEventIDs.length ? { correctiveEventIDs } : {}
+  };
+}
 function mapRecordChecked(record, mapping, eventTime) {
   const errors = [];
   const bizStep = resolve(mapping.bizStep, record, "bizStep", errors) ?? "";
   const disposition = resolve(mapping.disposition, record, "disposition", errors);
   const readPoint = resolve(mapping.readPoint, record, "readPoint", errors);
   const bizLocation = resolve(mapping.bizLocation, record, "bizLocation", errors);
+  const errorDeclaration = resolveErrorDeclaration(mapping.errorDeclaration, record, errors);
   if (mapping.type === "TransformationEvent") {
     const inputEPCList = resolveList(mapping.inputEPCList, record, "inputEPCList", errors);
     const inputQuantityList = resolveQuantityList(mapping.inputQuantityList, record, "inputQuantityList", errors);
@@ -3306,6 +3381,7 @@ function mapRecordChecked(record, mapping, eventTime) {
         ...outputEPCList.length ? { outputEPCList } : {},
         ...outputQuantityList.length ? { outputQuantityList } : {},
         ...transformationID ? { transformationID } : {},
+        ...errorDeclaration ? { errorDeclaration } : {},
         readPoint,
         bizLocation
       }),
@@ -3327,6 +3403,7 @@ function mapRecordChecked(record, mapping, eventTime) {
         /* 없는 쪽은 **필드를 만들지 않는다** — 빈 배열을 실으면 「자식이 없다」고 말하는 것이 된다. */
         ...childEPCs.length ? { childEPCs } : {},
         ...childQuantityList.length ? { childQuantityList } : {},
+        ...errorDeclaration ? { errorDeclaration } : {},
         readPoint,
         bizLocation
       }),
@@ -3349,6 +3426,7 @@ function mapRecordChecked(record, mapping, eventTime) {
       epcList: epc ? [epc] : [],
       ...quantityList.length ? { quantityList } : {},
       ...ilmd ? { ilmd } : {},
+      ...errorDeclaration ? { errorDeclaration } : {},
       readPoint,
       bizLocation
     }),
@@ -3377,11 +3455,13 @@ function ingest(records, rules, opts) {
       rejected.push({ record, errors });
       continue;
     }
+    const note = typeof record["description"] === "string" ? String(record["description"]).trim() : "";
     accepted.push({
       eventId: `${opts.tenantId}-ingest-${++seq}`,
       eventType: `epcis.${ev.type}`,
       eventTime: ev.eventTime,
       tenantId: opts.tenantId,
+      ...note ? { description: note } : {},
       data: ev
     });
   }
@@ -3650,6 +3730,21 @@ function deriveAttentions(view, acked, nowIso, thresholds) {
         suggestedAction: { code: "act.repair", command: CMD.resourceRepair, args: { resourceId: m.id } }
       });
     }
+    if (m.silentMs !== void 0 && m.longestSilenceBeforeMs !== void 0 && m.silentMs > m.longestSilenceBeforeMs) {
+      out.push({
+        id: `silent:${m.id}`,
+        kind: "equipment-silent",
+        severity: "medium",
+        anchor: { moverId: m.id, locationId: m.location },
+        params: {
+          moverId: m.id,
+          ...m.location ? { locationId: m.location } : {},
+          silentMs: m.silentMs,
+          longestBeforeMs: m.longestSilenceBeforeMs,
+          ...m.status ? { lastStatus: m.status } : {}
+        }
+      });
+    }
   }
   for (const n of view.locations) {
     for (const c of n.criteria ?? []) {
@@ -5010,9 +5105,13 @@ var FlowEngine = class {
         if (cs.length) criteriaOf.set(n.id, cs);
       }
     }
+    const silence = typeof this.observer?.equipmentSilence === "function" ? this.observer.equipmentSilence() : void 0;
     const out = deriveAttentions(
       {
-        equipment: [...this.equipment.values()],
+        equipment: [...this.equipment.values()].map((m) => {
+          const s = silence?.get(m.id);
+          return s ? { ...m, silentMs: s.silentMs, longestSilenceBeforeMs: s.longestBeforeMs } : m;
+        }),
         locations: [...this.locations.values()].map((n) => {
           const criteria = criteriaOf.get(n.id);
           return criteria?.length ? { ...n, criteria } : n;
@@ -9172,7 +9271,8 @@ function ingestOperationalRecords(records, opts) {
     const spec = SPECS[kind];
     const r = record;
     const errors = [];
-    const unknown = Object.keys(r).filter((k) => k !== "at" && spec.fields[k] === void 0);
+    const ENVELOPE_FIELDS = ["at", "description"];
+    const unknown = Object.keys(r).filter((k) => !ENVELOPE_FIELDS.includes(k) && spec.fields[k] === void 0);
     if (unknown.length) errors.push(`${kind}: \uACC4\uC57D\uC5D0 \uC5C6\uB294 \uD544\uB4DC \u2014 ${unknown.join(", ")}`);
     for (const name of spec.required) {
       const v = r[name];
@@ -9256,11 +9356,13 @@ function ingestOperationalRecords(records, opts) {
       rejected.push({ record, errors });
       continue;
     }
+    const note = typeof r.description === "string" ? String(r.description).trim() : "";
     accepted.push({
       eventId: `${opts.tenantId}-op-${kind}-${++seq}`,
       eventType: spec.eventType,
       eventTime: new Date(atMs).toISOString(),
       tenantId: opts.tenantId,
+      ...note ? { description: note } : {},
       data
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.7.63",
+  "version": "0.7.65",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {