@operato/twin-kernel 0.7.48 → 0.7.50

package/dist/domain-catalog.d.ts

@@ -70,8 +70,14 @@ export interface TwinAxisInfo {
      * 이 칸이 없던 동안 소비처는 `id`·`key`·`gtin` 을 **짐작**했고, 그래서 화면이 실재하는 항목을
      * 「식별자 없음 — 참조할 수 없는 항목」으로 보였다. 값은 있는데 가리킬 수 없다고 말한 것이다.
      * 짐작을 없애고 선언이 답한다 — 축이 사는 자리(`path`)를 선언하는 것과 같은 이유다.
+     *
+     * ── 여럿을 받는다 (2026-08-22) ────────────────────────────────────────────
+     * 정체성이 **한 칸으로 정해지지 않는 축**이 있다. 물품이 그렇다: 직렬 물품은 `epc` 가 유일하지만,
+     * 비직렬 로트가 자리마다 나뉘면 개체를 구별하는 것은 `subLotId` 다(같은 로트의 두 부분은 같은 `epc`
+     * 를 갖는다 — §`ItemState.subLotId`). 계약이 그 규칙을 말할 수 없으면 소비처가 다시 짐작한다.
+     * 그래서 **차례**를 받는다: 앞에서 값이 있는 첫 칸이 이긴다.
      */
-    idField?: string;
+    idField?: string | string[];
     /**
      * 이 축을 **어디서 읽나.**
      *

package/dist/domain-catalog.js

@@ -97,6 +97,27 @@ export const TWIN_AXES = [
         standardClass: { isa95: 'OperationsRequest', epcis: 'TransactionEvent' }, systems: LOGISTICS },
     { axis: 'tasks', label: 'twin.axis.tasks', kind: 'instance', source: 'state', historical: true,
         standardClass: { isa95: 'SegmentResponse', epcis: 'TransformationEvent' }, systems: LOGISTICS },
+    /*
+     * ── 물품이 축이 아니었다 (2026-08-22) ──────────────────────────────────────
+     * 트윈에서 **수가 가장 많은 것**이 물품인데(실측: 엔티티 3,611 중 2,400 · hatio-us 는 2,805) 그것을
+     * 가리켜 걸어 들어갈 자리가 없었다. 지도와 집약 태그에는 이미 보이는데 「모델 살펴보기」에는 문이
+     * 없었다 — 사용자가 트윈에 가장 자주 묻는 것이 「내 물건이 어디 있나」이므로 그것은 접근 장벽이다.
+     *
+     * 성격은 `orders`·`tasks` 와 같다: 상태에 살고, 저널에 이력이 있고, 원본이 낸 것을 트윈이 관측한다.
+     * 그래서 같은 조합(`instance` · `state` · `historical`)이다.
+     *
+     * ── 표준 대응 ─────────────────────────────────────────────────────────────
+     * ISA-95 는 `MaterialLot` 이다 — 물품은 「무슨 품목인가」(정의)가 아니라 「그 품목의 이 덩어리」이고,
+     * 위치·수량·부분(`MaterialSubLot`)을 그 자리가 든다. EPCIS 는 `ObjectEvent` 다: 개체가 생기고
+     * 관측되고 사라지는 것을 그 사건이 말한다.
+     *
+     * ── 무엇이 이 항목을 가리키나 ─────────────────────────────────────────────
+     * `subLotId ?? epc` 다. 짐작에 맡기면 `gtin` 으로 떨어지고, 그러면 **같은 품목의 물품 전부가 한
+     * 식별자로 뭉친다** — 화면이 2,400개를 몇 개로 보인다.
+     */
+    { axis: 'items', label: 'twin.axis.items', kind: 'instance', source: 'state', historical: true,
+        idField: ['subLotId', 'epc'],
+        standardClass: { isa95: 'MaterialLot', epcis: 'ObjectEvent' }, systems: LOGISTICS },
     /*
      * ── 에너지가 더하는 개념은 **하나**다 (2026-08-14, §10 6.5단계) ──────────────
      *
@@ -163,6 +184,24 @@ export const TWIN_RELATIONS = [
     { from: 'tasks', field: 'toNode', target: { kind: 'axis', axis: 'locations' }, via: 'twin.rel.at', optional: true },
     { from: 'tasks', field: 'resourceRef', target: { kind: 'axis', axis: 'equipment' }, via: 'twin.rel.by', optional: true },
     { from: 'tasks', field: 'personnel[]', target: { kind: 'axis', axis: 'persons' }, via: 'twin.rel.crew', optional: true },
+    /*
+     * 물품의 관계 (2026-08-22) — 없으면 축이 **걸어 들어갈 수 없는 목록**이 된다.
+     *
+     * `location` 은 필수다 — 물품은 언제나 어딘가에 있다(그것이 물품의 뜻이다). 나머지는 선택이다:
+     * 물류단위에 담기지 않은 물품, 자산에 실리지 않은 팔레트가 정상이다.
+     *
+     * `parent` 는 **물품 축을 자기 자신으로** 가리킨다(팔레트에 담긴 상자 — EPCIS `AggregationEvent`).
+     * `carriedBy` 는 다른 축이다 — 반복사용 자산(GRAI)이 물류단위를 실어 나른다(§`FlowItem.carriedBy`).
+     *
+     * 관계 이름은 **소문자 한 낱말**이다(`twin.rel.<name>`) — 기존 열여덟 개가 그 규율이고 시험이 지킨다.
+     *
+     * 품목(`gtin`)은 오더와 **같은 규율**이다: 자재 키가 아니라 GS1 품목 참조이므로 축을 직접 가리키지
+     * 않고 `external` 로 둔다. 축을 가리키게 적으면 없는 필드를 가리키는 선언이 된다.
+     */
+    { from: 'items', field: 'location', target: { kind: 'axis', axis: 'locations' }, via: 'twin.rel.at' },
+    { from: 'items', field: 'parent', target: { kind: 'axis', axis: 'items' }, via: 'twin.rel.parent', optional: true },
+    { from: 'items', field: 'carriedBy', target: { kind: 'axis', axis: 'assets' }, via: 'twin.rel.asset', optional: true },
+    { from: 'items', field: 'gtin', target: { kind: 'external', entity: 'gs1.itemRef' }, via: 'twin.rel.item', optional: true },
     /*
      * 자격을 검증한 시험 — **여덟 갈래.** 자원(개체)과 등급 양쪽이 가리킨다: 표준이 그 둘 모두에 이
      * 참조를 두었기 때문이다(개체는 "이 사람이 통과했다", 등급은 "이 자격은 이 시험을 요구한다").

package/dist/flow-engine.d.ts

@@ -1,4 +1,4 @@
-import type { TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, OeeMetrics, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, ScenarioOverride, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, StructureShift, IdentityGroundingView, IdentityDeclaration } from './contract.ts';
+import type { TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, OeeMetrics, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, ScenarioOverride, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, TaskStatus, StructureShift, IdentityGroundingView, IdentityDeclaration } from './contract.ts';
 import type { EpcisEvent, BizTransactionElement } from './epcis.ts';
 import type { AllocationPolicy, SlotView } from './allocation-policy.ts';
 import type { DurationEstimator, DurationContext } from './duration-estimator.ts';
@@ -130,7 +130,18 @@ export interface FlowEquipment extends EffectivePeriod {
 export interface FlowTask {
     id: string;
     kind: string;
-    status: 'created' | 'in-progress' | 'completed';
+    /**
+     * **작업 상태 — 어휘는 하나다**(`TaskStatus`: created · assigned · in-progress · completed).
+     *
+     * 예전에는 여기만 셋이었다(`assigned` 없음). 시뮬레이션은 배정과 착수를 한 번에 하므로 그것으로
+     * 충분했지만, **미러는 원본이 말한 것을 그대로 들고 있어야 한다** — 그리고 주의 계산은 이미
+     * `assigned` 를 기다리고 있었다(§`collectAttentions`: `status === 'created' || status === 'assigned'`).
+     * 즉 그 자리는 영원히 오지 않는 값을 기다렸다.
+     *
+     * 시뮬 경로의 거동은 바뀌지 않는다: 시뮬은 `assigned` 를 만들지 않고, 배정 루프는 `created` 만
+     * 집는다(§`assign`). 넓힌 것은 **관측이 말한 사실을 담을 자리**다.
+     */
+    status: TaskStatus;
     /**
      * **실제로 들어가고 나온 자재** — ISA-95 `JobResponse.MaterialActual`.
      *
@@ -700,7 +711,26 @@ export declare abstract class FlowEngine implements TwinKernel {
             id: string;
             since: string;
         }[];
-    }, orders?: OrderStatusDelta[]): void;
+    }, orders?: OrderStatusDelta[], 
+    /**
+     * **무엇을 하러 심나** — 기본은 씨앗이다(외부 호출자 전부가 그것이다).
+     *
+     * ── 왜 이 구별이 생겼나 (2026-08-22 실측) ─────────────────────────────────
+     * 이 함수는 원래 **스냅샷으로 커널을 세우는 문**이다(웜스타트·fork·예측). 그 목적에서는 딛고 설
+     * 물품·오더가 없는 작업을 빼는 것이 옳다 — 굴릴 수 없는 작업을 심으면 첫 틱에서 없는 자리를
+     * 가리킨다.
+     *
+     * 그런데 `settleObserved()` 가 **미러 자신의 관측을 옮길 때도** 같은 함수를 쓴다. 목적이 다르다:
+     * 미러는 그 작업을 굴리지 않는다 — **들은 것을 말할 뿐이다.** 그런데 규칙이 하나였으므로 관측된
+     * 사실이 씨앗 규칙에 걸려 사라졌다.
+     *
+     * 실측: 포천 미러의 저널에 `task.status` 5,786건이 있고 투영기로 접으면 작업 2,881건인데
+     * `getSnapshot().tasks` 는 **0** 이었다. 화면은 「아직 하나도 없습니다」라고 말했고 사용자가
+     * 반나절을 찾았다. 재현하면 관측기 5건 → 커널 0건이고, 걸린 조건은 오더였다.
+     *
+     * 그래서 규칙을 둘로 쪼개지 않고 **목적을 밝힌다.** 같은 함수, 같은 주입 경로, 다른 판정 하나다.
+     */
+    purpose?: 'seed' | 'observe'): void;
     /**
      * what-if 구성 변주 — **선언을 덮어쓴다**(fork 대상). 바꿨으면 true.
      *

package/dist/flow-engine.js

@@ -388,7 +388,20 @@ export class ItemStore {
     clone() {
         const out = new ItemStore();
         for (const [k, it] of this.map)
-            out.set(k, structuredClone(it));
+            out.map.set(k, structuredClone(it));
+        /*
+         * ── 색인은 **베껴 온다** (2026-08-22) ─────────────────────────────────────
+         * 예전에는 항목마다 `set()` 을 불러 색인을 다시 쌓았다. 색인이 하나일 때는 그 비용이 묻혔는데,
+         * 품목 색인이 생기면서 항목마다 Map 조회 둘 + Set 삽입 둘이 됐다 — 그리고 `fork()` 가 이 함수를
+         * 쓴다. 예측은 회차마다 사본을 뜨므로 그 비용이 곧바로 예측 비용이다.
+         *
+         * 사본은 **원본과 같은 배치**이므로 색인을 다시 계산할 이유가 없다. 그룹마다 Set 하나를 만들어
+         * 베낀다. 어긋날 위험은 `indexDrift()` 가 지킨다(시나리오를 돌린 뒤 그 값으로 확인한다).
+         */
+        for (const [loc, keys] of this.byLocation)
+            out.byLocation.set(loc, new Set(keys));
+        for (const [g, keys] of this.byGtin)
+            out.byGtin.set(g, new Set(keys));
         return out;
     }
     /*
@@ -819,7 +832,26 @@ export class FlowEngine {
         this.seedDanglingRefs += dropped;
         return { kept, dropped };
     }
-    hydrateObserved(snap, orders = []) {
+    hydrateObserved(snap, orders = [], 
+    /**
+     * **무엇을 하러 심나** — 기본은 씨앗이다(외부 호출자 전부가 그것이다).
+     *
+     * ── 왜 이 구별이 생겼나 (2026-08-22 실측) ─────────────────────────────────
+     * 이 함수는 원래 **스냅샷으로 커널을 세우는 문**이다(웜스타트·fork·예측). 그 목적에서는 딛고 설
+     * 물품·오더가 없는 작업을 빼는 것이 옳다 — 굴릴 수 없는 작업을 심으면 첫 틱에서 없는 자리를
+     * 가리킨다.
+     *
+     * 그런데 `settleObserved()` 가 **미러 자신의 관측을 옮길 때도** 같은 함수를 쓴다. 목적이 다르다:
+     * 미러는 그 작업을 굴리지 않는다 — **들은 것을 말할 뿐이다.** 그런데 규칙이 하나였으므로 관측된
+     * 사실이 씨앗 규칙에 걸려 사라졌다.
+     *
+     * 실측: 포천 미러의 저널에 `task.status` 5,786건이 있고 투영기로 접으면 작업 2,881건인데
+     * `getSnapshot().tasks` 는 **0** 이었다. 화면은 「아직 하나도 없습니다」라고 말했고 사용자가
+     * 반나절을 찾았다. 재현하면 관측기 5건 → 커널 0건이고, 걸린 조건은 오더였다.
+     *
+     * 그래서 규칙을 둘로 쪼개지 않고 **목적을 밝힌다.** 같은 함수, 같은 주입 경로, 다른 판정 하나다.
+     */
+    purpose = 'seed') {
         /* 확인 처리를 먼저 이어받는다 — 아래에서 상태를 주입하면 곧바로 주목 신호가 계산되므로, 늦게
          * 이어받으면 그 한 번은 확인 안 된 것으로 계산된다(화면이 잠깐 빨개진다). */
         for (const id of snap.acked ?? [])
@@ -869,7 +901,15 @@ export class FlowEngine {
             const prev = this.equipment.get(m.id);
             this.equipment.set(m.id, {
                 ...(prev ?? {}),
-                id: m.id, kind: m.kind, location: m.location ?? '', ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), status: m.status ?? 'idle', taskId: null,
+                /*
+                 * `taskId` — **관측이면 원본이 말한 값이다.**
+                 *
+                 * 씨앗에서는 `null` 로 두고 작업 복원이 다시 세운다(작업이 함께 오지 않으면 그 자원이 영원히
+                 * 잡혀 있게 되므로). 그런데 관측에서는 `equipment.status` 가 이 값을 **직접 실어 온다** —
+                 * 상태(busy)는 그 축에서 받고 묶임은 작업에서 되세우면, 같은 사실의 두 조각이 서로 다른 축에서
+                 * 오게 되고 한쪽만 도착한 순간 어긋난다.
+                 */
+                id: m.id, kind: m.kind, location: m.location ?? '', ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), status: m.status ?? 'idle', taskId: purpose === 'observe' ? (m.taskId ?? null) : null,
                 runMs: oee?.runMs ?? 0, setupMs: oee?.setupMs ?? 0, downMs: oee?.downMs ?? 0,
                 goodCount: oee?.goodCount ?? 0, scrapCount: oee?.scrapCount ?? 0,
                 /*
@@ -902,7 +942,10 @@ export class FlowEngine {
             const prev = this.persons.get(p.id);
             this.persons.set(p.id, {
                 ...(prev ?? {}),
-                id: p.id, personnelClassIds: p.personnelClassIds ?? prev?.personnelClassIds, status: 'idle', taskId: null,
+                /* 설비와 같은 규율 — 관측이면 원본이 말한 상태·묶임을 지킨다(씨앗이면 작업 복원이 세운다). */
+                id: p.id, personnelClassIds: p.personnelClassIds ?? prev?.personnelClassIds,
+                status: purpose === 'observe' ? (p.status ?? 'idle') : 'idle',
+                taskId: purpose === 'observe' ? (p.taskId ?? null) : null,
                 ...(p.location ? { location: p.location } : {}),
                 ...(p.properties ? { properties: p.properties } : {}),
                 ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}),
@@ -916,7 +959,10 @@ export class FlowEngine {
             const prev = this.assets.get(a.id);
             this.assets.set(a.id, {
                 ...(prev ?? {}),
-                id: a.id, assetClassIds: a.assetClassIds ?? prev?.assetClassIds, location: a.location, status: 'idle', taskId: null, carrying: a.carrying,
+                /* 설비·사람과 같은 규율 — 관측이면 원본이 말한 상태·묶임을 지킨다. */
+                id: a.id, assetClassIds: a.assetClassIds ?? prev?.assetClassIds, location: a.location,
+                status: purpose === 'observe' ? (a.status ?? 'idle') : 'idle',
+                taskId: purpose === 'observe' ? (a.taskId ?? null) : null, carrying: a.carrying,
                 ...(a.properties ? { properties: a.properties } : {}),
                 ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}),
                 /* 결과도 이어받는다 — 잃으면 예측이 **자격 만료를 모르는 현장**에서 출발한다(낙관 쪽으로 치우친다). */
@@ -1009,38 +1055,83 @@ export class FlowEngine {
         }
         /* 작업이 딛고 설 오더를 먼저 세운다 — 순서가 뒤바뀌면 아래 확인이 언제나 "없다" 로 답한다. */
         const seededOrderIds = new Set(this.orders.keys());
-        let orphaned = 0;
+        /*
+         * **떨어뜨린 이유를 따로 센다** — 예전에는 하나로 세고 「whose item is no longer in state」라고
+         * 말했다. 그런데 오더에 걸린 경우도 같은 문장을 썼고, 그것을 본 사람이 물품 쪽을 반나절 뒤졌다.
+         * 원인을 지어내는 문장은 없는 것보다 나쁘다.
+         */
+        let droppedNoItem = 0;
+        let droppedNoOrder = 0;
+        let droppedCompleted = 0;
+        /*
+         * **씨앗이냐 관측 정착이냐** — 아래 셋을 거를지 말지가 여기서 갈린다(§`purpose`).
+         *
+         *   씨앗(seed)      굴릴 수 없는 작업은 뺀다. 심으면 첫 틱에서 없는 자리를 가리킨다.
+         *   관측(observe)   **거르지 않는다.** 미러는 그 작업을 굴리지 않고, 들은 것을 말한다.
+         */
+        const filtering = purpose === 'seed';
         for (const t of snap.tasks ?? []) {
-            if (t.status === 'completed')
+            if (filtering && t.status === 'completed') {
+                droppedCompleted++;
                 continue;
+            }
             const ref = t.itemRefs?.[0];
-            if (ref && !this.itemByRef(ref)) {
-                orphaned++;
+            if (filtering && ref && !this.itemByRef(ref)) {
+                droppedNoItem++;
                 continue;
             }
             /* 오더도 같다 — 이미 이행된 오더는 주입하지 않으므로(위 `remaining <= 0`), 그 오더에 딸린 작업만
                남으면 완료 시점에 없는 오더를 딛는다. 주입 단계에서 함께 뺀다. */
-            if (t.orderId && !seededOrderIds.has(t.orderId)) {
-                orphaned++;
+            if (filtering && t.orderId && !seededOrderIds.has(t.orderId)) {
+                droppedNoOrder++;
                 continue;
             }
             const known = typeof t.remainingMs === 'number' && Number.isFinite(t.remainingMs);
             this.tasks.set(t.id, {
                 id: t.id, kind: t.kind,
-                status: known && t.status === 'in-progress' ? 'in-progress' : 'created',
+                /*
+                 * **관측이면 들은 상태를 그대로 둔다.** 씨앗이면 굴릴 수 있는 모양으로 맞춘다(남은 시간을
+                 * 모르는 작업을 `in-progress` 로 심으면 끝나지 않는다).
+                 *
+                 * 예전에는 관측 경로에서도 이 줄이 상태를 다시 썼다 — 원본이 `completed` 라고 말한 작업이
+                 * `created` 로, `assigned` 도 `created` 로 바뀌었다. 공정 타임라인·현장 성과·주의 목록이
+                 * 모두 이 축을 읽으므로, 여기서 뭉개면 그 셋이 함께 거짓이 된다.
+                 */
+                status: purpose === 'observe' ? t.status : known && t.status === 'in-progress' ? 'in-progress' : 'created',
                 /* 이미 일어난 자재 이동은 **씨앗에도 남는다** — 잃으면 실적이 재기동마다 지워진다. */
                 ...(t.materialActual?.length ? { materialActual: t.materialActual.map(r => ({ ...r })) } : {}),
                 itemEpc: t.itemRefs?.[0] ?? '',
                 fromNode: t.fromNode ?? '', toNode: t.toNode ?? '',
-                resource: known && t.status === 'in-progress' ? (t.resourceRef ?? null) : null,
+                /*
+                 * 자원 참조는 **작업 자신의 사실**이다. 씨앗에서는 굴릴 수 있는 작업만 자원을 잡게 하지만
+                 * (남은 시간을 모르면 배정 루프가 다시 잡아야 한다), 관측에서는 원본이 말한 참조를 지운 이유가
+                 * 없다 — 지우면 「어느 설비가 이 일을 하고 있나」가 화면에서 사라진다.
+                 */
+                resource: purpose === 'observe' ? (t.resourceRef ?? null) : known && t.status === 'in-progress' ? (t.resourceRef ?? null) : null,
                 remainingMs: known ? t.remainingMs : (t.durationMs ?? 0),
                 startedAtSimMs: t.startedAtSimMs,
                 durationMs: t.durationMs ?? (known ? t.remainingMs : 0),
                 orderId: t.orderId,
                 intent: t.intent
             });
-            /* 진행 중으로 살린 작업은 그 자원을 점유한 상태여야 한다(자원이 동시에 다른 일을 받지 않게). */
-            if (known && t.status === 'in-progress' && t.resourceRef) {
+            /*
+             * 투입 인원은 **작업이 들고 있는 사실**이므로 관측에서도 그대로 옮긴다(위 `set` 에서 빠져 있어
+             * 아래에서 채운다 — 씨앗 시절 진행 중인 작업에만 필요했던 자리다).
+             */
+            if (purpose === 'observe' && t.personnel?.length) {
+                const restored = this.tasks.get(t.id);
+                if (restored)
+                    restored.personnel = [...t.personnel];
+            }
+            /*
+             * **자원의 상태는 여기서 정하지 않는다 — 관측일 때는.**
+             *
+             * 씨앗에서는 필요하다: 진행 중인 작업을 심었으면 그 설비가 다른 일을 또 받으면 안 되므로 점유를
+             * 표시한다. 그런데 미러에서는 설비·사람의 상태가 **자기 관측 축**(`equipment.status`,
+             * `person.status`)에서 온다. 작업 하나로 그것을 덮으면 원본이 「유휴」라고 말한 설비를 트윈이
+             * 「바쁘다」고 말한다 — 축이 둘이 되고, 어느 쪽이 사실인지 알 수 없게 된다.
+             */
+            if (purpose === 'seed' && known && t.status === 'in-progress' && t.resourceRef) {
                 const mv = this.equipment.get(t.resourceRef);
                 if (mv) {
                     mv.status = 'busy';
@@ -1048,7 +1139,7 @@ export class FlowEngine {
                 }
             }
             /* 사람도 같다 — 진행 중이던 작업에 투입돼 있던 사람은 여전히 점유되어 있어야 한다. */
-            if (known && t.status === 'in-progress') {
+            if (purpose === 'seed' && known && t.status === 'in-progress') {
                 const restored = this.tasks.get(t.id);
                 if (restored)
                     restored.personnel = t.personnel ? [...t.personnel] : undefined;
@@ -1061,9 +1152,21 @@ export class FlowEngine {
                 }
             }
         }
-        if (orphaned) {
-            console.warn(`[twin-kernel] seed skipped ${orphaned} in-flight task(s) whose item is no longer in state — ` +
-                'they cannot be continued (the item was consumed/shipped, or the observation did not carry it).');
+        /*
+         * **무엇을 왜 뺐는지 그대로 말한다.** 씨앗에서만 나온다(관측은 빼지 않는다).
+         *
+         * 예전 문장은 셋을 하나로 뭉쳐 「whose item is no longer in state」라고 했다. 오더에 걸린 것을
+         * 물품 탓으로 말했고, 그 문장을 읽은 사람이 물품 쪽을 뒤졌다. 원인을 지어내는 문장은 침묵보다 나쁘다.
+         */
+        const droppedTotal = droppedNoItem + droppedNoOrder + droppedCompleted;
+        if (droppedTotal) {
+            const why = [
+                droppedNoItem ? `${droppedNoItem} whose item is not in state` : '',
+                droppedNoOrder ? `${droppedNoOrder} whose order is not in state` : '',
+                droppedCompleted ? `${droppedCompleted} already completed` : ''
+            ].filter(Boolean).join(' · ');
+            console.warn(`[twin-kernel] seed skipped ${droppedTotal} task(s) — ${why}. ` +
+                'They cannot be continued by a simulation. (A mirror keeps them: hydrateObserved(…, …, "observe").)');
         }
     }
     /**
@@ -1710,7 +1813,14 @@ export class FlowEngine {
         if (!this.observedDirty || !this.observer)
             return;
         this.observedDirty = false;
-        this.hydrateObserved(this.observer.snapshot());
+        /*
+         * **목적을 밝힌다 — 이것은 씨앗이 아니라 관측 정착이다**(§`hydrateObserved` 의 `purpose`).
+         *
+         * 이 한 낱말이 없던 동안 미러의 작업이 씨앗 규칙에 걸려 사라졌다: 포천 미러의 저널에
+         * `task.status` 5,786건이 있는데 `getSnapshot().tasks` 는 0 이었고, 화면은 「아직 하나도
+         * 없습니다」라고 말했다. 미러는 그 작업을 굴리지 않는다 — 들은 것을 말할 뿐이다.
+         */
+        this.hydrateObserved(this.observer.snapshot(), [], 'observe');
     }
     /** 구독자 목록 — 관측 재방출용(private handlers 에 접근). */
     observedHandlers() {

package/dist-cjs/index.cjs

@@ -2549,6 +2549,34 @@ var TWIN_AXES = [
     standardClass: { isa95: "SegmentResponse", epcis: "TransformationEvent" },
     systems: LOGISTICS
   },
+  /*
+   * ── 물품이 축이 아니었다 (2026-08-22) ──────────────────────────────────────
+   * 트윈에서 **수가 가장 많은 것**이 물품인데(실측: 엔티티 3,611 중 2,400 · hatio-us 는 2,805) 그것을
+   * 가리켜 걸어 들어갈 자리가 없었다. 지도와 집약 태그에는 이미 보이는데 「모델 살펴보기」에는 문이
+   * 없었다 — 사용자가 트윈에 가장 자주 묻는 것이 「내 물건이 어디 있나」이므로 그것은 접근 장벽이다.
+   *
+   * 성격은 `orders`·`tasks` 와 같다: 상태에 살고, 저널에 이력이 있고, 원본이 낸 것을 트윈이 관측한다.
+   * 그래서 같은 조합(`instance` · `state` · `historical`)이다.
+   *
+   * ── 표준 대응 ─────────────────────────────────────────────────────────────
+   * ISA-95 는 `MaterialLot` 이다 — 물품은 「무슨 품목인가」(정의)가 아니라 「그 품목의 이 덩어리」이고,
+   * 위치·수량·부분(`MaterialSubLot`)을 그 자리가 든다. EPCIS 는 `ObjectEvent` 다: 개체가 생기고
+   * 관측되고 사라지는 것을 그 사건이 말한다.
+   *
+   * ── 무엇이 이 항목을 가리키나 ─────────────────────────────────────────────
+   * `subLotId ?? epc` 다. 짐작에 맡기면 `gtin` 으로 떨어지고, 그러면 **같은 품목의 물품 전부가 한
+   * 식별자로 뭉친다** — 화면이 2,400개를 몇 개로 보인다.
+   */
+  {
+    axis: "items",
+    label: "twin.axis.items",
+    kind: "instance",
+    source: "state",
+    historical: true,
+    idField: ["subLotId", "epc"],
+    standardClass: { isa95: "MaterialLot", epcis: "ObjectEvent" },
+    systems: LOGISTICS
+  },
   /*
    * ── 에너지가 더하는 개념은 **하나**다 (2026-08-14, §10 6.5단계) ──────────────
    *
@@ -2623,6 +2651,24 @@ var TWIN_RELATIONS = [
   { from: "tasks", field: "toNode", target: { kind: "axis", axis: "locations" }, via: "twin.rel.at", optional: true },
   { from: "tasks", field: "resourceRef", target: { kind: "axis", axis: "equipment" }, via: "twin.rel.by", optional: true },
   { from: "tasks", field: "personnel[]", target: { kind: "axis", axis: "persons" }, via: "twin.rel.crew", optional: true },
+  /*
+   * 물품의 관계 (2026-08-22) — 없으면 축이 **걸어 들어갈 수 없는 목록**이 된다.
+   *
+   * `location` 은 필수다 — 물품은 언제나 어딘가에 있다(그것이 물품의 뜻이다). 나머지는 선택이다:
+   * 물류단위에 담기지 않은 물품, 자산에 실리지 않은 팔레트가 정상이다.
+   *
+   * `parent` 는 **물품 축을 자기 자신으로** 가리킨다(팔레트에 담긴 상자 — EPCIS `AggregationEvent`).
+   * `carriedBy` 는 다른 축이다 — 반복사용 자산(GRAI)이 물류단위를 실어 나른다(§`FlowItem.carriedBy`).
+   *
+   * 관계 이름은 **소문자 한 낱말**이다(`twin.rel.<name>`) — 기존 열여덟 개가 그 규율이고 시험이 지킨다.
+   *
+   * 품목(`gtin`)은 오더와 **같은 규율**이다: 자재 키가 아니라 GS1 품목 참조이므로 축을 직접 가리키지
+   * 않고 `external` 로 둔다. 축을 가리키게 적으면 없는 필드를 가리키는 선언이 된다.
+   */
+  { from: "items", field: "location", target: { kind: "axis", axis: "locations" }, via: "twin.rel.at" },
+  { from: "items", field: "parent", target: { kind: "axis", axis: "items" }, via: "twin.rel.parent", optional: true },
+  { from: "items", field: "carriedBy", target: { kind: "axis", axis: "assets" }, via: "twin.rel.asset", optional: true },
+  { from: "items", field: "gtin", target: { kind: "external", entity: "gs1.itemRef" }, via: "twin.rel.item", optional: true },
   /*
    * 자격을 검증한 시험 — **여덟 갈래.** 자원(개체)과 등급 양쪽이 가리킨다: 표준이 그 둘 모두에 이
    * 참조를 두었기 때문이다(개체는 "이 사람이 통과했다", 등급은 "이 자격은 이 시험을 요구한다").
@@ -3515,7 +3561,9 @@ var ItemStore = class _ItemStore {
    */
   clone() {
     const out = new _ItemStore();
-    for (const [k, it] of this.map) out.set(k, structuredClone(it));
+    for (const [k, it] of this.map) out.map.set(k, structuredClone(it));
+    for (const [loc, keys] of this.byLocation) out.byLocation.set(loc, new Set(keys));
+    for (const [g, keys] of this.byGtin) out.byGtin.set(g, new Set(keys));
     return out;
   }
   /*
@@ -3916,7 +3964,7 @@ var FlowEngine = class {
     this.seedDanglingRefs += dropped;
     return { kept, dropped };
   }
-  hydrateObserved(snap, orders = []) {
+  hydrateObserved(snap, orders = [], purpose = "seed") {
     for (const id of snap.acked ?? []) this._acked.add(id);
     for (const e of snap.attentionSince ?? []) if (e?.id && e.since) this._attentionSince.set(e.id, e.since);
     for (const n of snap.locations) {
@@ -3946,12 +3994,20 @@ var FlowEngine = class {
       const prev = this.equipment.get(m.id);
       this.equipment.set(m.id, {
         ...prev ?? {},
+        /*
+         * `taskId` — **관측이면 원본이 말한 값이다.**
+         *
+         * 씨앗에서는 `null` 로 두고 작업 복원이 다시 세운다(작업이 함께 오지 않으면 그 자원이 영원히
+         * 잡혀 있게 되므로). 그런데 관측에서는 `equipment.status` 가 이 값을 **직접 실어 온다** —
+         * 상태(busy)는 그 축에서 받고 묶임은 작업에서 되세우면, 같은 사실의 두 조각이 서로 다른 축에서
+         * 오게 되고 한쪽만 도착한 순간 어긋난다.
+         */
         id: m.id,
         kind: m.kind,
         location: m.location ?? "",
         ...m.homeLocation ? { homeLocation: m.homeLocation } : {},
         status: m.status ?? "idle",
-        taskId: null,
+        taskId: purpose === "observe" ? m.taskId ?? null : null,
         runMs: oee?.runMs ?? 0,
         setupMs: oee?.setupMs ?? 0,
         downMs: oee?.downMs ?? 0,
@@ -3982,10 +4038,11 @@ var FlowEngine = class {
       const prev = this.persons.get(p.id);
       this.persons.set(p.id, {
         ...prev ?? {},
+        /* 설비와 같은 규율 — 관측이면 원본이 말한 상태·묶임을 지킨다(씨앗이면 작업 복원이 세운다). */
         id: p.id,
         personnelClassIds: p.personnelClassIds ?? prev?.personnelClassIds,
-        status: "idle",
-        taskId: null,
+        status: purpose === "observe" ? p.status ?? "idle" : "idle",
+        taskId: purpose === "observe" ? p.taskId ?? null : null,
         ...p.location ? { location: p.location } : {},
         ...p.properties ? { properties: p.properties } : {},
         ...p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {},
@@ -3998,11 +4055,12 @@ var FlowEngine = class {
       const prev = this.assets.get(a.id);
       this.assets.set(a.id, {
         ...prev ?? {},
+        /* 설비·사람과 같은 규율 — 관측이면 원본이 말한 상태·묶임을 지킨다. */
         id: a.id,
         assetClassIds: a.assetClassIds ?? prev?.assetClassIds,
         location: a.location,
-        status: "idle",
-        taskId: null,
+        status: purpose === "observe" ? a.status ?? "idle" : "idle",
+        taskId: purpose === "observe" ? a.taskId ?? null : null,
         carrying: a.carrying,
         ...a.properties ? { properties: a.properties } : {},
         ...a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {},
@@ -4071,43 +4129,66 @@ var FlowEngine = class {
       });
     }
     const seededOrderIds = new Set(this.orders.keys());
-    let orphaned = 0;
+    let droppedNoItem = 0;
+    let droppedNoOrder = 0;
+    let droppedCompleted = 0;
+    const filtering = purpose === "seed";
     for (const t of snap.tasks ?? []) {
-      if (t.status === "completed") continue;
+      if (filtering && t.status === "completed") {
+        droppedCompleted++;
+        continue;
+      }
       const ref = t.itemRefs?.[0];
-      if (ref && !this.itemByRef(ref)) {
-        orphaned++;
+      if (filtering && ref && !this.itemByRef(ref)) {
+        droppedNoItem++;
         continue;
       }
-      if (t.orderId && !seededOrderIds.has(t.orderId)) {
-        orphaned++;
+      if (filtering && t.orderId && !seededOrderIds.has(t.orderId)) {
+        droppedNoOrder++;
         continue;
       }
       const known = typeof t.remainingMs === "number" && Number.isFinite(t.remainingMs);
       this.tasks.set(t.id, {
         id: t.id,
         kind: t.kind,
-        status: known && t.status === "in-progress" ? "in-progress" : "created",
+        /*
+         * **관측이면 들은 상태를 그대로 둔다.** 씨앗이면 굴릴 수 있는 모양으로 맞춘다(남은 시간을
+         * 모르는 작업을 `in-progress` 로 심으면 끝나지 않는다).
+         *
+         * 예전에는 관측 경로에서도 이 줄이 상태를 다시 썼다 — 원본이 `completed` 라고 말한 작업이
+         * `created` 로, `assigned` 도 `created` 로 바뀌었다. 공정 타임라인·현장 성과·주의 목록이
+         * 모두 이 축을 읽으므로, 여기서 뭉개면 그 셋이 함께 거짓이 된다.
+         */
+        status: purpose === "observe" ? t.status : known && t.status === "in-progress" ? "in-progress" : "created",
         /* 이미 일어난 자재 이동은 **씨앗에도 남는다** — 잃으면 실적이 재기동마다 지워진다. */
         ...t.materialActual?.length ? { materialActual: t.materialActual.map((r) => ({ ...r })) } : {},
         itemEpc: t.itemRefs?.[0] ?? "",
         fromNode: t.fromNode ?? "",
         toNode: t.toNode ?? "",
-        resource: known && t.status === "in-progress" ? t.resourceRef ?? null : null,
+        /*
+         * 자원 참조는 **작업 자신의 사실**이다. 씨앗에서는 굴릴 수 있는 작업만 자원을 잡게 하지만
+         * (남은 시간을 모르면 배정 루프가 다시 잡아야 한다), 관측에서는 원본이 말한 참조를 지운 이유가
+         * 없다 — 지우면 「어느 설비가 이 일을 하고 있나」가 화면에서 사라진다.
+         */
+        resource: purpose === "observe" ? t.resourceRef ?? null : known && t.status === "in-progress" ? t.resourceRef ?? null : null,
         remainingMs: known ? t.remainingMs : t.durationMs ?? 0,
         startedAtSimMs: t.startedAtSimMs,
         durationMs: t.durationMs ?? (known ? t.remainingMs : 0),
         orderId: t.orderId,
         intent: t.intent
       });
-      if (known && t.status === "in-progress" && t.resourceRef) {
+      if (purpose === "observe" && t.personnel?.length) {
+        const restored = this.tasks.get(t.id);
+        if (restored) restored.personnel = [...t.personnel];
+      }
+      if (purpose === "seed" && known && t.status === "in-progress" && t.resourceRef) {
         const mv = this.equipment.get(t.resourceRef);
         if (mv) {
           mv.status = "busy";
           mv.taskId = t.id;
         }
       }
-      if (known && t.status === "in-progress") {
+      if (purpose === "seed" && known && t.status === "in-progress") {
         const restored = this.tasks.get(t.id);
         if (restored) restored.personnel = t.personnel ? [...t.personnel] : void 0;
         for (const id of t.personnel ?? []) {
@@ -4119,9 +4200,15 @@ var FlowEngine = class {
         }
       }
     }
-    if (orphaned) {
+    const droppedTotal = droppedNoItem + droppedNoOrder + droppedCompleted;
+    if (droppedTotal) {
+      const why = [
+        droppedNoItem ? `${droppedNoItem} whose item is not in state` : "",
+        droppedNoOrder ? `${droppedNoOrder} whose order is not in state` : "",
+        droppedCompleted ? `${droppedCompleted} already completed` : ""
+      ].filter(Boolean).join(" \xB7 ");
       console.warn(
-        `[twin-kernel] seed skipped ${orphaned} in-flight task(s) whose item is no longer in state \u2014 they cannot be continued (the item was consumed/shipped, or the observation did not carry it).`
+        `[twin-kernel] seed skipped ${droppedTotal} task(s) \u2014 ${why}. They cannot be continued by a simulation. (A mirror keeps them: hydrateObserved(\u2026, \u2026, "observe").)`
       );
     }
   }
@@ -4704,7 +4791,7 @@ var FlowEngine = class {
   settleObserved() {
     if (!this.observedDirty || !this.observer) return;
     this.observedDirty = false;
-    this.hydrateObserved(this.observer.snapshot());
+    this.hydrateObserved(this.observer.snapshot(), [], "observe");
   }
   /** 구독자 목록 — 관측 재방출용(private handlers 에 접근). */
   observedHandlers() {

package/package.json

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