@operato/twin-kernel 0.7.50 → 0.7.51

package/dist/contract.js

@@ -1,6 +1,36 @@
 /*
  * Face 1 — 3채널 계약 (walking skeleton 범위).
  * 설계 SoT: operato-twin/design/integration/face1-contract.md
+ *
+ * ── 이 계약을 넓히려는 사람이 먼저 읽을 것 (2026-08-23) ──────────────────────
+ *
+ * 사실은 두 종류이고, 종류가 그 자리를 정한다.
+ *
+ *   **파생** — 시각만으로 넘어가는 판정. 근무 밖 · 교대 · 능력 · 자리 상태 · 납기 대비 · 진척.
+ *     · **저장하지 않는다.** 저장하면 장부가 둘이 되고, 시각이 지나도 옛 값이 남는다.
+ *     · **입력으로 받지 않는다.** 원본이 단정하면 답이 둘이 되고 커널이 어느 쪽을 믿을지 정해야 한다.
+ *     · 계산할 수 없으면 **답하지 않는다.** 모르는 값을 숫자로 만들면 화면이 그것을 사실로 그린다
+ *       (`dueStatusOf` 가 그 규율을 먼저 적었다: 납기가 없으면 「늦지 않았다」가 아니라 「판단할 수 없다」).
+ *     · 파생이 **불가능할 때만** 원본의 단정을 쓴다. 그 순서가 선언돼 있어야 한다(`offShift`·`progress`).
+ *
+ *   **누적** — 열린 구간에 쌓이는 값. 가동·준비·고장 시간 · 양품/불량 수 · 조건이 성립한 시각.
+ *     · **다시 계산할 수 없다.** 원천은 「이번 창에서 지금까지 얼마」를 모른다.
+ *     · 그래서 **재기동을 넘어 이어받는다.** 잃으면 오류 없이 값이 작아진다 — 가장 비싼 종류의 침묵이다.
+ *
+ * 그리고 **자리를 늘리는 조건은 하나다: 전이로 표현할 수 없는 사실.**
+ *
+ * 「자리가 없다」와 「담을 수 없다」는 다르다. 전자는 대개 이미 있는 축을 못 찾은 것이다 — 작업의
+ * 실제 착수·완료·대기는 **전이의 `eventTime`** 이 말하고(`task-fold`), 대기는 그것으로 계산된다
+ * (`kpi-fold`: `waitMs = startedMs − createdMs`). 원본이 전이를 놓쳐 보내면 **놓친 전이를 그 시각으로
+ * 함께 내는 것**이 답이고, 속성을 새로 여는 것이 아니다.
+ *
+ * 그러므로 원본을 붙이는 사람이 물어야 하는 것은 「이 컬럼을 실을 자리가 있나」가 아니라
+ * **「원본이 말하는 이 사실을 커널의 어휘로 어떻게 옮기나」**다. 컬럼 단위로 물으면 원본이 열이면
+ * 축도 열이 된다 — 2026-08-23 에 축 다섯을 열었다가 그 이유로 되돌렸다.
+ *
+ * 열지 않기로 한 것과 그 조건은 `design/04-decisions.md` ADR-0039 에 있다. 넓히기 전에 그 표를 본다.
+ * 지키는 하네스: `derived-not-input` · `actuals-come-from-transitions` · `accumulators-survive-restart` ·
+ * `purpose-conformance`.
  */
 /**
  * 자리의 상태 — **포화도에서 파생한다.** 저장하는 값이 아니다.

package/dist/flow-engine.d.ts

@@ -78,6 +78,15 @@ export interface FlowPerson extends EffectivePeriod {
     };
     /** 근무 캘린더 — 표준 `WorkCalendarEntry`(복수). 있으면 `window` 보다 이것을 본다. */
     workCalendar?: WorkCalendarEntry[];
+    /**
+     * **원본이 말한 근무 밖 표시** — 캘린더가 없을 때만 쓰는 값이다.
+     *
+     * 캘린더가 있으면 시각으로 판정한다(`offCalendar`) — 저장값을 함께 보면 교대 안으로 돌아왔을 때 옛
+     * `true` 가 남는다. 그런데 근무 캘린더를 주지 않는 원본이 실 시스템에 흔하고, 그때 이것이 **유일한
+     * 답**이다. 리듀서가 이미 그 규율로 이 값을 지키고 있었는데(§`observed-reducer` offShift) 커널 상태에
+     * 자리가 없어 옮기는 자리에서 잃고 있었다.
+     */
+    offShift?: boolean;
     /** 지금 어디에 있나 — 표준 `Person.OperationalLocation`. 커널은 사람을 움직이지 않는다(마스터·관측이 말한다). */
     location?: string;
     /** 자원 속성 — 표준 `PersonProperty`. */
@@ -165,6 +174,15 @@ export interface FlowTask {
     /** 예정 창 — 표준 `JobOrder.StartTime`/`EndTime`. 실제 착수와 다른 축. */
     startTime?: string;
     endTime?: string;
+    /**
+     * **원본이 말한 진척** — 커널이 계산할 수 없을 때만 쓰는 값이다(§`progressOf`).
+     *
+     * 파생이 가능하면(소요를 알면) 파생이 이긴다. 이 자리는 파생을 대신하는 것이 아니라 **파생이
+     * 불가능할 때 침묵하지 않기 위한 것**이다 — 사람 교대(`offShift`)가 세워 둔 규율과 같다.
+     *
+     * 관측에서만 채운다. 시뮬은 자기 소요를 알므로 이 값을 쓸 일이 없다.
+     */
+    progress?: number;
     /** 이 작업에 투입된 사람들 — 설비와 별개 축(설비 1대 + 작업자 2명이 동시에 잡힌다). */
     personnel?: string[];
     /** 이 작업에 투입된 물리 자산(팔레트 등). */
@@ -1559,7 +1577,25 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 로트는 LGTIN 이면 식별자 안에 있고, 직렬 개체는 마스터데이터(`ilmd`)에 실려 온다.
      */
     protected itemState(i: FlowItem): ItemState;
-    protected progressOf(t: FlowTask): number;
+    /**
+     * 진척 — **모르면 답하지 않는다.**
+     *
+     * ── 무엇이 틀려 있었나 (2026-08-23 실측) ───────────────────────────────────
+     * 예전에는 `durationMs <= 0` 이면 `1` 을 돌려줬다. 시뮬에서는 그것이 맞다(소요 0 = 즉시 끝나는 일).
+     * 그런데 **미러에서 `durationMs` 0 은 「즉시」가 아니라 「모른다」다** — 원본이 소요를 말해 주지
+     * 않으면 씨앗 경로가 0 으로 메우고, 그러면 이 함수가 **진행 중인 작업을 100% 라고 말한다.**
+     *
+     * 실측: 소요를 주지 않는 원본의 진행 중 작업이 `progress: 1` 로 나왔다. 「모름」을 「완료」로 말하는
+     * 것이고, 화면은 그것을 사실로 그린다.
+     *
+     * 시뮬에서는 이 반환이 바뀌지 않는다: 소요 0 인 작업은 배정된 tick 안에서 끝나므로 **진행 중으로
+     * 관측되지 않는다**(`status = 'in-progress'; remainingMs = durationMs` → 다음 진행에서 즉시 완료).
+     * 즉 `durationMs <= 0` 이면서 진행 중인 작업은 미러 경로에서만 나온다.
+     *
+     * 모를 때 원본이 진척을 말해 주었다면 그 값을 쓴다 — 그 규칙은 부르는 쪽에 있다(§`getSnapshot`).
+     * 이 함수는 **커널이 계산할 수 있나**만 답한다.
+     */
+    protected progressOf(t: FlowTask): number | undefined;
     private generate;
     private processOrders;
     /**

package/dist/flow-engine.js

@@ -946,6 +946,15 @@ export class FlowEngine {
                 id: p.id, personnelClassIds: p.personnelClassIds ?? prev?.personnelClassIds,
                 status: purpose === 'observe' ? (p.status ?? 'idle') : 'idle',
                 taskId: purpose === 'observe' ? (p.taskId ?? null) : null,
+                /*
+                 * 원본이 말한 근무 밖 표시 — **관측일 때만, 그리고 선언이 없을 때만 쓰인다.**
+                 *
+                 * 이 규율의 원본 자리는 리듀서다(§`offShift`: 「선언이 없을 때만 받는다 — 선언이 있으면
+                 * `snapshot()` 이 시각으로 판정하고, 저장값을 함께 두면 교대 안으로 돌아왔을 때 옛 `true` 가
+                 * 남는다」). 그런데 이 자리가 그 값을 **떨어뜨리고 있었다** — 리듀서가 지킨 것을 여기서 잃었다.
+                 * 근무 캘린더가 없는 원본(실 시스템에 흔하다)에서는 그것이 유일한 답이다.
+                 */
+                ...(purpose === 'observe' && p.offShift ? { offShift: true } : {}),
                 ...(p.location ? { location: p.location } : {}),
                 ...(p.properties ? { properties: p.properties } : {}),
                 ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}),
@@ -1026,11 +1035,35 @@ export class FlowEngine {
             const remaining = lines.length
                 ? lines.reduce((s, l) => s + l.requested, 0)
                 : Math.max(0, (o.requested ?? 0) - (o.fulfilled ?? 0));
-            if (remaining <= 0)
-                continue; // 이미 이행 완료 → 예측 대상 아님
+            /*
+             * ── **씨앗은 남은 데맨드로, 미러는 들은 그대로** (2026-08-23) ──────────────
+             *
+             * 아래 세 값(`status`·`requested`·`fulfilled`)은 씨앗의 규약이다: 씨앗은 「무엇이 남았나」로
+             * 미래를 굴리므로 요청 10·이행 4 를 **요청 6·이행 0·상태 created** 로 다시 표현한다. 그리고 이미
+             * 이행된 오더는 예측 대상이 아니므로 건너뛴다.
+             *
+             * **미러에는 전부 틀렸다.** 미러는 굴리지 않고 들은 것을 말한다. 실측(포천 미러):
+             *
+             *   원본이 말한 것   picking · 요청 10 · 이행 4 · 진척 0.4
+             *   커널이 낸 것     created · 요청  6 · 이행 0 · 진척 0     ← 40% 된 오더가 0% 로 보였다
+             *
+             * 그리고 이행 완료된 오더는 **상태에서 아예 사라졌다** — 원본이 그 오더가 있다고 말하는데
+             * 트윈은 없다고 말한다. 오더의 상태 낱말은 계약이 도메인에 넘긴 것인데(`picking`·`shipped`…)
+             * 씨앗 규약이 그것을 커널 낱말로 덮고 있었다.
+             *
+             * 이것은 작업에서 고친 것과 **같은 결함의 세 번째 사례**다(§`purpose`): 한 함수가 두 목적을 겸하고
+             * 씨앗 규약이 관측에 새어 나온다.
+             */
+            const observing = purpose === 'observe';
+            if (!observing && remaining <= 0)
+                continue; // 씨앗: 이미 이행 완료 → 예측 대상 아님
             const resolved = this.resolvedAllocated(o.allocated);
             this.orders.set(o.orderId, {
-                id: o.orderId, kind: o.kind, status: 'created', requested: remaining, fulfilled: 0,
+                id: o.orderId,
+                kind: o.kind,
+                status: observing ? (o.status ?? 'created') : 'created',
+                requested: observing ? (o.requested ?? 0) : remaining,
+                fulfilled: observing ? (o.fulfilled ?? 0) : 0,
                 /* **확보해 둔 것과 거래번호를 이어받는다.** 비우면 되살아난 오더가 아무것도 안 잡은 것처럼
                    보이고, 그 오더의 진행 중 작업이 완료될 때 계보가 입력 없이 나간다. 상태가 말해 주지
                    않으면(옛 저널) 그때는 비는 것이 사실이다 — 없는 것을 지어내지 않는다. */
@@ -1039,7 +1072,9 @@ export class FlowEngine {
                 /* 레시피도 함께 — 품목만 이어받으면 되살아난 오더가 「무엇으로」를 모르고, 그 오더의
                    남은 공정·소요가 다른 레시피 기준으로 계산된다(같은 품목에 대체 레시피가 있다). */
                 ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
-                bizTransaction: o.bizTransaction ?? '', allocated: resolved.kept, picked: [], shipmentEpc: null, lines,
+                bizTransaction: o.bizTransaction ?? '', allocated: resolved.kept, picked: [], shipmentEpc: null,
+                /* 라인도 같다 — 씨앗은 남은 양만 남기고, 미러는 원본이 말한 요청·이행을 그대로 든다. */
+                lines: observing ? (o.lines ?? []).map(l => ({ ...l })) : lines,
                 ...(resolved.dropped ? { seedIncomplete: true } : {}),
                 /* **보류를 이어받는다** — 잃으면 씨앗이 사람이 일부러 멈춘 오더를 다시 계획해 내보낸다.
                    씨앗 왕복 대조가 이것을 잡았다(그 전에는 사람이 코드를 읽어야만 알 수 있었다). */
@@ -1112,7 +1147,12 @@ export class FlowEngine {
                 startedAtSimMs: t.startedAtSimMs,
                 durationMs: t.durationMs ?? (known ? t.remainingMs : 0),
                 orderId: t.orderId,
-                intent: t.intent
+                intent: t.intent,
+                /*
+                 * 원본이 말한 진척 — **관측일 때만, 그리고 커널이 계산할 수 없을 때 쓰인다**(§`progressOf`).
+                 * 씨앗 경로에서는 싣지 않는다: 씨앗은 굴러가면서 자기 소요로 진척을 만든다.
+                 */
+                ...(purpose === 'observe' && typeof t.progress === 'number' ? { progress: t.progress } : {})
             });
             /*
              * 투입 인원은 **작업이 들고 있는 사실**이므로 관측에서도 그대로 옮긴다(위 `set` 에서 빠져 있어
@@ -1425,8 +1465,13 @@ export class FlowEngine {
             equipment: [...this.equipment.values()].map(m => {
                 const s = { id: m.id, kind: m.kind, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m), held: m.held, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), ...(m.testResults ? { testResults: m.testResults } : {}), capability: this.capabilityOfResource(m, m.kind ? [m.kind] : [], this.classDefs.equipment), origin: 'master', ...(this.offShift(m) ? { offShift: true, ...this.offReason(m) } : {}), ...this.effectivePart(m), ...(this.shiftOf(m) ? { shift: this.shiftOf(m) } : {}), ...energyFieldsOf(m) };
                 const t = m.taskId ? this.tasks.get(m.taskId) : undefined;
-                if (t && t.status === 'in-progress' && t.intent !== 'process')
-                    s.motion = { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs - (t.durationMs - t.remainingMs), durationMs: t.durationMs, progress: this.progressOf(t), elapsedMs: t.durationMs - t.remainingMs };
+                /*
+                 * 이동 구간은 **소요를 알 때만** 낸다. 모르면 아래 산수가 전부 0 이나 음수가 되고, 화면은 「제자리에서
+                 * 다 끝난 이동」을 그린다 — 원본이 소요를 주지 않는 미러에서 실제로 그랬다(§`progressOf`).
+                 */
+                const motionProgress = t && t.status === 'in-progress' && t.intent !== 'process' ? this.progressOf(t) : undefined;
+                if (t && motionProgress !== undefined)
+                    s.motion = { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs - (t.durationMs - t.remainingMs), durationMs: t.durationMs, progress: motionProgress, elapsedMs: t.durationMs - t.remainingMs };
                 return s;
             }),
             assets: [...this.assets.values()].map(a => {
@@ -1455,10 +1500,17 @@ export class FlowEngine {
                    물을 수 없다(사실은 자기 집에서 나온다). 판정은 아래 `capability` 가 이미 답한다. */
                 if (p.testResults)
                     st.testResults = p.testResults;
+                /*
+                 * 근무 밖 판정 — **선언이 있으면 선언이 이기고, 없을 때만 원본이 말한 값을 쓴다.**
+                 * 진척(`progressOf`)과 같은 순서다. 선언이 있는데 저장값을 함께 보면 교대 안으로 돌아왔을 때
+                 * 옛 `true` 가 남는다(리듀서가 그 이유를 적어 두었다).
+                 */
                 if (this.personOffShift(p)) {
                     st.offShift = true;
                     Object.assign(st, this.offReason(p));
                 }
+                else if (p.offShift && !p.workCalendar?.length)
+                    st.offShift = true;
                 const sh = this.shiftOf(p);
                 if (sh)
                     st.shift = sh;
@@ -1479,7 +1531,26 @@ export class FlowEngine {
                 fromNode: t.fromNode, toNode: t.toNode, resourceRef: t.resource ?? undefined, orderId: t.orderId,
                 ...(t.intent ? { intent: t.intent } : {}),
                 ...(t.durationMs ? { durationMs: t.durationMs } : {}),
-                ...(t.status === 'in-progress' ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: this.progressOf(t) } : {}),
+                /*
+                 * 진척은 **커널이 계산한 값이 먼저, 못 하면 원본이 말한 값**이다(§`progressOf`).
+                 *
+                 * 이 순서는 사람 교대(`offShift`)가 세워 둔 규율과 같다: 파생이 가능하면 파생이 이기고, 파생이
+                 * 불가능할 때만 원본의 단정을 쓴다. 둘 다 없으면 **싣지 않는다** — 「모른다」를 숫자로 만들지 않는다.
+                 *
+                 * 예전에는 원본이 진척을 말해도 조용히 버렸다(문이 받아 놓고 파생이 덮었다). 넣었는데 사라지는
+                 * 것이 이 시스템에서 가장 비싼 침묵이다.
+                 */
+                ...(t.status === 'in-progress'
+                    ? {
+                        remainingMs: t.remainingMs,
+                        startedAtSimMs: t.startedAtSimMs,
+                        ...(() => {
+                            const derived = this.progressOf(t);
+                            const p = derived ?? t.progress;
+                            return p === undefined ? {} : { progress: p };
+                        })()
+                    }
+                    : {}),
                 ...(t.personnel?.length ? { personnel: t.personnel.slice() } : {}),
                 ...(t.assets?.length ? { assets: t.assets.slice() } : {}),
                 ...(t.resources?.length ? { resources: t.resources.slice() } : {}),
@@ -3418,7 +3489,29 @@ export class FlowEngine {
             ...(i.ilmd ? { ilmd: i.ilmd } : {})
         };
     }
-    progressOf(t) { return t.durationMs <= 0 ? 1 : Math.min(1, Math.max(0, (t.durationMs - t.remainingMs) / t.durationMs)); }
+    /**
+     * 진척 — **모르면 답하지 않는다.**
+     *
+     * ── 무엇이 틀려 있었나 (2026-08-23 실측) ───────────────────────────────────
+     * 예전에는 `durationMs <= 0` 이면 `1` 을 돌려줬다. 시뮬에서는 그것이 맞다(소요 0 = 즉시 끝나는 일).
+     * 그런데 **미러에서 `durationMs` 0 은 「즉시」가 아니라 「모른다」다** — 원본이 소요를 말해 주지
+     * 않으면 씨앗 경로가 0 으로 메우고, 그러면 이 함수가 **진행 중인 작업을 100% 라고 말한다.**
+     *
+     * 실측: 소요를 주지 않는 원본의 진행 중 작업이 `progress: 1` 로 나왔다. 「모름」을 「완료」로 말하는
+     * 것이고, 화면은 그것을 사실로 그린다.
+     *
+     * 시뮬에서는 이 반환이 바뀌지 않는다: 소요 0 인 작업은 배정된 tick 안에서 끝나므로 **진행 중으로
+     * 관측되지 않는다**(`status = 'in-progress'; remainingMs = durationMs` → 다음 진행에서 즉시 완료).
+     * 즉 `durationMs <= 0` 이면서 진행 중인 작업은 미러 경로에서만 나온다.
+     *
+     * 모를 때 원본이 진척을 말해 주었다면 그 값을 쓴다 — 그 규칙은 부르는 쪽에 있다(§`getSnapshot`).
+     * 이 함수는 **커널이 계산할 수 있나**만 답한다.
+     */
+    progressOf(t) {
+        if (!(t.durationMs > 0))
+            return undefined;
+        return Math.min(1, Math.max(0, (t.durationMs - t.remainingMs) / t.durationMs));
+    }
     generate() {
         for (const g of this.gens) {
             while (this.clockMs >= g.nextMs) {

package/dist-cjs/index.cjs

@@ -4043,6 +4043,15 @@ var FlowEngine = class {
         personnelClassIds: p.personnelClassIds ?? prev?.personnelClassIds,
         status: purpose === "observe" ? p.status ?? "idle" : "idle",
         taskId: purpose === "observe" ? p.taskId ?? null : null,
+        /*
+         * 원본이 말한 근무 밖 표시 — **관측일 때만, 그리고 선언이 없을 때만 쓰인다.**
+         *
+         * 이 규율의 원본 자리는 리듀서다(§`offShift`: 「선언이 없을 때만 받는다 — 선언이 있으면
+         * `snapshot()` 이 시각으로 판정하고, 저장값을 함께 두면 교대 안으로 돌아왔을 때 옛 `true` 가
+         * 남는다」). 그런데 이 자리가 그 값을 **떨어뜨리고 있었다** — 리듀서가 지킨 것을 여기서 잃었다.
+         * 근무 캘린더가 없는 원본(실 시스템에 흔하다)에서는 그것이 유일한 답이다.
+         */
+        ...purpose === "observe" && p.offShift ? { offShift: true } : {},
         ...p.location ? { location: p.location } : {},
         ...p.properties ? { properties: p.properties } : {},
         ...p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {},
@@ -4094,14 +4103,15 @@ var FlowEngine = class {
     for (const o of observedOrders) {
       const lines = (o.lines ?? []).map((l) => ({ gtin: l.gtin, requested: l.requested - (l.fulfilled ?? 0) })).filter((l) => l.requested > 0);
       const remaining = lines.length ? lines.reduce((s, l) => s + l.requested, 0) : Math.max(0, (o.requested ?? 0) - (o.fulfilled ?? 0));
-      if (remaining <= 0) continue;
+      const observing = purpose === "observe";
+      if (!observing && remaining <= 0) continue;
       const resolved = this.resolvedAllocated(o.allocated);
       this.orders.set(o.orderId, {
         id: o.orderId,
         kind: o.kind,
-        status: "created",
-        requested: remaining,
-        fulfilled: 0,
+        status: observing ? o.status ?? "created" : "created",
+        requested: observing ? o.requested ?? 0 : remaining,
+        fulfilled: observing ? o.fulfilled ?? 0 : 0,
         /* **확보해 둔 것과 거래번호를 이어받는다.** 비우면 되살아난 오더가 아무것도 안 잡은 것처럼
            보이고, 그 오더의 진행 중 작업이 완료될 때 계보가 입력 없이 나간다. 상태가 말해 주지
            않으면(옛 저널) 그때는 비는 것이 사실이다 — 없는 것을 지어내지 않는다. */
@@ -4114,7 +4124,8 @@ var FlowEngine = class {
         allocated: resolved.kept,
         picked: [],
         shipmentEpc: null,
-        lines,
+        /* 라인도 같다 — 씨앗은 남은 양만 남기고, 미러는 원본이 말한 요청·이행을 그대로 든다. */
+        lines: observing ? (o.lines ?? []).map((l) => ({ ...l })) : lines,
         ...resolved.dropped ? { seedIncomplete: true } : {},
         /* **보류를 이어받는다** — 잃으면 씨앗이 사람이 일부러 멈춘 오더를 다시 계획해 내보낸다.
            씨앗 왕복 대조가 이것을 잡았다(그 전에는 사람이 코드를 읽어야만 알 수 있었다). */
@@ -4175,7 +4186,12 @@ var FlowEngine = class {
         startedAtSimMs: t.startedAtSimMs,
         durationMs: t.durationMs ?? (known ? t.remainingMs : 0),
         orderId: t.orderId,
-        intent: t.intent
+        intent: t.intent,
+        /*
+         * 원본이 말한 진척 — **관측일 때만, 그리고 커널이 계산할 수 없을 때 쓰인다**(§`progressOf`).
+         * 씨앗 경로에서는 싣지 않는다: 씨앗은 굴러가면서 자기 소요로 진척을 만든다.
+         */
+        ...purpose === "observe" && typeof t.progress === "number" ? { progress: t.progress } : {}
       });
       if (purpose === "observe" && t.personnel?.length) {
         const restored = this.tasks.get(t.id);
@@ -4436,7 +4452,8 @@ var FlowEngine = class {
       equipment: [...this.equipment.values()].map((m) => {
         const s = { id: m.id, kind: m.kind, location: m.location, ...m.homeLocation ? { homeLocation: m.homeLocation } : {}, status: m.status, taskId: m.taskId ?? void 0, oee: this.oeeOf(m), held: m.held, ...m.properties ? { properties: m.properties } : {}, ...m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}, ...m.testResults ? { testResults: m.testResults } : {}, capability: this.capabilityOfResource(m, m.kind ? [m.kind] : [], this.classDefs.equipment), origin: "master", ...this.offShift(m) ? { offShift: true, ...this.offReason(m) } : {}, ...this.effectivePart(m), ...this.shiftOf(m) ? { shift: this.shiftOf(m) } : {}, ...energyFieldsOf(m) };
         const t = m.taskId ? this.tasks.get(m.taskId) : void 0;
-        if (t && t.status === "in-progress" && t.intent !== "process") s.motion = { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs - (t.durationMs - t.remainingMs), durationMs: t.durationMs, progress: this.progressOf(t), elapsedMs: t.durationMs - t.remainingMs };
+        const motionProgress = t && t.status === "in-progress" && t.intent !== "process" ? this.progressOf(t) : void 0;
+        if (t && motionProgress !== void 0) s.motion = { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs - (t.durationMs - t.remainingMs), durationMs: t.durationMs, progress: motionProgress, elapsedMs: t.durationMs - t.remainingMs };
         return s;
       }),
       assets: [...this.assets.values()].map((a) => {
@@ -4458,7 +4475,7 @@ var FlowEngine = class {
         if (this.personOffShift(p)) {
           st.offShift = true;
           Object.assign(st, this.offReason(p));
-        }
+        } else if (p.offShift && !p.workCalendar?.length) st.offShift = true;
         const sh = this.shiftOf(p);
         if (sh) st.shift = sh;
         Object.assign(st, this.effectivePart(p));
@@ -4484,7 +4501,24 @@ var FlowEngine = class {
         orderId: t.orderId,
         ...t.intent ? { intent: t.intent } : {},
         ...t.durationMs ? { durationMs: t.durationMs } : {},
-        ...t.status === "in-progress" ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: this.progressOf(t) } : {},
+        /*
+         * 진척은 **커널이 계산한 값이 먼저, 못 하면 원본이 말한 값**이다(§`progressOf`).
+         *
+         * 이 순서는 사람 교대(`offShift`)가 세워 둔 규율과 같다: 파생이 가능하면 파생이 이기고, 파생이
+         * 불가능할 때만 원본의 단정을 쓴다. 둘 다 없으면 **싣지 않는다** — 「모른다」를 숫자로 만들지 않는다.
+         *
+         * 예전에는 원본이 진척을 말해도 조용히 버렸다(문이 받아 놓고 파생이 덮었다). 넣었는데 사라지는
+         * 것이 이 시스템에서 가장 비싼 침묵이다.
+         */
+        ...t.status === "in-progress" ? {
+          remainingMs: t.remainingMs,
+          startedAtSimMs: t.startedAtSimMs,
+          ...(() => {
+            const derived = this.progressOf(t);
+            const p = derived ?? t.progress;
+            return p === void 0 ? {} : { progress: p };
+          })()
+        } : {},
         ...t.personnel?.length ? { personnel: t.personnel.slice() } : {},
         ...t.assets?.length ? { assets: t.assets.slice() } : {},
         ...t.resources?.length ? { resources: t.resources.slice() } : {},
@@ -6186,8 +6220,27 @@ var FlowEngine = class {
       ...i.ilmd ? { ilmd: i.ilmd } : {}
     };
   }
+  /**
+   * 진척 — **모르면 답하지 않는다.**
+   *
+   * ── 무엇이 틀려 있었나 (2026-08-23 실측) ───────────────────────────────────
+   * 예전에는 `durationMs <= 0` 이면 `1` 을 돌려줬다. 시뮬에서는 그것이 맞다(소요 0 = 즉시 끝나는 일).
+   * 그런데 **미러에서 `durationMs` 0 은 「즉시」가 아니라 「모른다」다** — 원본이 소요를 말해 주지
+   * 않으면 씨앗 경로가 0 으로 메우고, 그러면 이 함수가 **진행 중인 작업을 100% 라고 말한다.**
+   *
+   * 실측: 소요를 주지 않는 원본의 진행 중 작업이 `progress: 1` 로 나왔다. 「모름」을 「완료」로 말하는
+   * 것이고, 화면은 그것을 사실로 그린다.
+   *
+   * 시뮬에서는 이 반환이 바뀌지 않는다: 소요 0 인 작업은 배정된 tick 안에서 끝나므로 **진행 중으로
+   * 관측되지 않는다**(`status = 'in-progress'; remainingMs = durationMs` → 다음 진행에서 즉시 완료).
+   * 즉 `durationMs <= 0` 이면서 진행 중인 작업은 미러 경로에서만 나온다.
+   *
+   * 모를 때 원본이 진척을 말해 주었다면 그 값을 쓴다 — 그 규칙은 부르는 쪽에 있다(§`getSnapshot`).
+   * 이 함수는 **커널이 계산할 수 있나**만 답한다.
+   */
   progressOf(t) {
-    return t.durationMs <= 0 ? 1 : Math.min(1, Math.max(0, (t.durationMs - t.remainingMs) / t.durationMs));
+    if (!(t.durationMs > 0)) return void 0;
+    return Math.min(1, Math.max(0, (t.durationMs - t.remainingMs) / t.durationMs));
   }
   generate() {
     for (const g of this.gens) {

package/package.json

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