@operato/twin-kernel 0.7.50 → 0.7.52

package/dist/contract.d.ts

@@ -7,7 +7,60 @@ export interface CanonicalEnvelope<T = unknown> {
     correlationId?: string;
     data: T;
 }
+/**
+ * 작업의 상태 — **ISA-95 근거.** 1차 출처: `JobOrderType.DispatchStatus`(지시 쪽) +
+ * `JobResponseType.JobState`(실적 쪽). 대조 기록: `design/plans/isa95-coverage.md` §3-2
+ * (「`tasks.status` ↔ `DispatchStatus`+`JobState`」).
+ *
+ * ── 왜 우리 이름을 쓰나 ─────────────────────────────────────────────────────
+ * 표준은 **지시(`JobOrder`)와 실적(`JobResponse`)을 나눈다.** 우리 `TaskState` 는 그 둘을 한 몸에
+ * 든다 — 상태 전이와 배정 결과를 함께 들고 진행·완료까지 같은 개체가 표현한다. 그래서 `jobOrders`
+ * 로 부르면 **표준 이름을 쓰면서 다른 뜻으로 쓰는 것**이 된다. 대조 문서가 그 판정을 적어 두었다.
+ *
+ * ── 왜 **닫혀** 있나 ────────────────────────────────────────────────────────
+ * 커널이 이 넷으로 접는다: 성과 폴드가 착수·완료로 갈리고(`foldTaskRecords`), 주목 계산이
+ * `created`·`assigned` 를 대기로 센다, 배정 루프는 `created` 만 집는다. 그러니 낱말이 하나 늘면
+ * 그 셋이 조용히 달라진다 — 유입 문이 이 넷만 받는 이유다(다른 낱말은 오류 없이 사라진다).
+ */
 export type TaskStatus = 'created' | 'assigned' | 'in-progress' | 'completed';
+/** 오더가 **종결 상태**로 인정되는 낱말 — 이 밖은 진행 중이다(§`isOrderTerminal`). */
+export declare const ORDER_TERMINAL_STATUS: readonly ["completed", "cancelled"];
+/**
+ * 이 오더는 **끝났나** — 판정을 한 곳에 둔다(`locationStatusOf`·`dueStatusOf` 와 같은 규율).
+ *
+ * ── 왜 함수여야 하나 (2026-08-23) ───────────────────────────────────────────
+ * 이 판정이 없던 동안 호스트의 성과 폴드가 **낱말을 동의어 목록으로 추론했다**
+ * (`completed`·`fulfilled`·`done`·`finished`). 그 방식이 낸 대가가 둘이다.
+ *
+ *  ① **원본의 낱말이 목록에 없으면 완료가 조용히 0 이 된다.** 실제로 그랬다 — 첫 실 시스템의
+ *     `FINISHED` 가 빠져 있었고, 사람이 화면을 보고 의심해서야 드러났다. 그리고 그때 목록에 낱말을
+ *     더한 것은 진짜 빈 자리(커넥터가 자기 상태 표를 안 쓰고 있었다)를 가린 땜빵이었다.
+ *  ② **시뮬 트윈에서는 언제나 0 이었다.** 시뮬은 오더를 이행하면서 `fulfilled` 만 올리고 `status` 는
+ *     바꾸지 않는다(그런 대입이 코드에 없다). 그래서 낱말로 묻는 판정은 시뮬의 완료를 **한 건도**
+ *     세지 못했다. 낱말이 틀린 것이 아니라 **묻는 축이 틀렸다.**
+ *
+ * ── 표준이 그 축을 이미 갈라 두었다 ─────────────────────────────────────────
+ * `orders` 는 `OperationsRequest` 쪽이고 그 상태는 `RequestState` 다 — **표준도 그 값을 열거하지
+ * 않는다.** 그래서 이 축이 열려 있는 것은 방언이 아니라 표준 정합이다. 대신 표준은 「됐나」를 **실적**
+ * 에서 읽는다(`JobResponse`·`SegmentResponse`, 그리고 요구는 `SegmentRequirement.Quantity`).
+ *
+ * 그러므로 이 판정의 1차 근거는 **양**이다: 요구한 만큼 이행됐으면 끝난 것이고, 그 사실은 어느 원본의
+ * 어느 낱말과도 무관하다. 낱말은 **양으로 말할 수 없는 종결**을 위해 함께 본다 — 취소, 그리고 요구량을
+ * 채우지 못한 채 닫힌 오더.
+ *
+ * ── 도메인이 상태에 다른 것을 적는다 ────────────────────────────────────────
+ * MES 커널은 이 자리에 **진행 단계**를 적는다(`op-<공정키>`, `blocked-seed-incomplete`). 그 값들은
+ * 종결이 아니므로 이 판정이 옳게 「아니다」로 답한다. 다만 진행 단계를 상태 문자열에 적는 것 자체가
+ * 표준의 모양은 아니다(그것은 `SegmentResponse` 의 일이다) — 그 빚은 ADR-0039 에 조건과 함께 적었다.
+ *
+ * 모르면 `false` 다 — 「끝나지 않았다」가 아니라 **「끝났다고 말할 근거가 없다」**이고, 성과는 근거가
+ * 있는 것만 센다(없는 완료를 세면 처리량이 조용히 부풀려진다).
+ */
+export declare function isOrderTerminal(o: {
+    status?: string;
+    requested?: number;
+    fulfilled?: number;
+}): boolean;
 /**
  * 자리의 상태 — **포화도에서 파생한다.** 저장하는 값이 아니다.
  *

package/dist/contract.js

@@ -1,7 +1,81 @@
 /*
  * 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`.
  */
+/** 오더가 **종결 상태**로 인정되는 낱말 — 이 밖은 진행 중이다(§`isOrderTerminal`). */
+export const ORDER_TERMINAL_STATUS = ['completed', 'cancelled'];
+/**
+ * 이 오더는 **끝났나** — 판정을 한 곳에 둔다(`locationStatusOf`·`dueStatusOf` 와 같은 규율).
+ *
+ * ── 왜 함수여야 하나 (2026-08-23) ───────────────────────────────────────────
+ * 이 판정이 없던 동안 호스트의 성과 폴드가 **낱말을 동의어 목록으로 추론했다**
+ * (`completed`·`fulfilled`·`done`·`finished`). 그 방식이 낸 대가가 둘이다.
+ *
+ *  ① **원본의 낱말이 목록에 없으면 완료가 조용히 0 이 된다.** 실제로 그랬다 — 첫 실 시스템의
+ *     `FINISHED` 가 빠져 있었고, 사람이 화면을 보고 의심해서야 드러났다. 그리고 그때 목록에 낱말을
+ *     더한 것은 진짜 빈 자리(커넥터가 자기 상태 표를 안 쓰고 있었다)를 가린 땜빵이었다.
+ *  ② **시뮬 트윈에서는 언제나 0 이었다.** 시뮬은 오더를 이행하면서 `fulfilled` 만 올리고 `status` 는
+ *     바꾸지 않는다(그런 대입이 코드에 없다). 그래서 낱말로 묻는 판정은 시뮬의 완료를 **한 건도**
+ *     세지 못했다. 낱말이 틀린 것이 아니라 **묻는 축이 틀렸다.**
+ *
+ * ── 표준이 그 축을 이미 갈라 두었다 ─────────────────────────────────────────
+ * `orders` 는 `OperationsRequest` 쪽이고 그 상태는 `RequestState` 다 — **표준도 그 값을 열거하지
+ * 않는다.** 그래서 이 축이 열려 있는 것은 방언이 아니라 표준 정합이다. 대신 표준은 「됐나」를 **실적**
+ * 에서 읽는다(`JobResponse`·`SegmentResponse`, 그리고 요구는 `SegmentRequirement.Quantity`).
+ *
+ * 그러므로 이 판정의 1차 근거는 **양**이다: 요구한 만큼 이행됐으면 끝난 것이고, 그 사실은 어느 원본의
+ * 어느 낱말과도 무관하다. 낱말은 **양으로 말할 수 없는 종결**을 위해 함께 본다 — 취소, 그리고 요구량을
+ * 채우지 못한 채 닫힌 오더.
+ *
+ * ── 도메인이 상태에 다른 것을 적는다 ────────────────────────────────────────
+ * MES 커널은 이 자리에 **진행 단계**를 적는다(`op-<공정키>`, `blocked-seed-incomplete`). 그 값들은
+ * 종결이 아니므로 이 판정이 옳게 「아니다」로 답한다. 다만 진행 단계를 상태 문자열에 적는 것 자체가
+ * 표준의 모양은 아니다(그것은 `SegmentResponse` 의 일이다) — 그 빚은 ADR-0039 에 조건과 함께 적었다.
+ *
+ * 모르면 `false` 다 — 「끝나지 않았다」가 아니라 **「끝났다고 말할 근거가 없다」**이고, 성과는 근거가
+ * 있는 것만 센다(없는 완료를 세면 처리량이 조용히 부풀려진다).
+ */
+export function isOrderTerminal(o) {
+    const status = String(o?.status ?? '').trim().toLowerCase();
+    if (ORDER_TERMINAL_STATUS.includes(status))
+        return true;
+    /* 양으로 판정 — 요구량이 없으면 판정하지 않는다(0 을 「다 됐다」로 읽지 않는다). */
+    const requested = o?.requested;
+    const fulfilled = o?.fulfilled;
+    if (typeof requested !== 'number' || !(requested > 0))
+        return false;
+    return typeof fulfilled === 'number' && fulfilled >= requested;
+}
 /**
  * 자리의 상태 — **포화도에서 파생한다.** 저장하는 값이 아니다.
  *

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

@@ -9,7 +9,7 @@
  * 통합 타입은 도메인 필드를 옵셔널로 넓혀(FlowItem.gtin?, FlowOrder.shipmentEpc? 등) 두 도메인을 담는다.
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowLocation 단일 base 방향과 정합.)
  */
-import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, identityGroundingOf } from "./contract.js";
+import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, isOrderTerminal, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, identityGroundingOf } from "./contract.js";
 import { ObservedReducer } from "./observed-reducer.js";
 import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR, CBV_BIZSTEP, objectUri, bizTransactionUri, gdtiUri } from "./epcis.js";
 import { OP_PARAM } from "./domain-definition.js";
@@ -217,7 +217,9 @@ thresholds) {
        지연으로도 정시로도 말하지 않는다). 이미 끝난 오더는 대상이 아니다.
        심각도는 얼마나 늦었는지로 구분한다 — 방금 넘긴 것과 하루 넘긴 것을 같게 부르면 신호가 무의미해진다. */
     for (const o of view.orders) {
-        if (o.status === 'completed' || o.status === 'fulfilled')
+        /* 끝난 오더는 지연 신호의 대상이 아니다 — 판정은 한 곳에 있다(§`isOrderTerminal`).
+           예전에는 여기서 낱말 둘을 견줬고, 그러면 양으로만 끝난 오더(시뮬이 그렇다)가 영원히 늦었다고 말한다. */
+        if (isOrderTerminal(o))
             continue;
         if (dueStatusOf(o, nowIso) !== 'late')
             continue;
@@ -946,6 +948,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 +1037,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 +1074,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 +1149,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 +1467,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 +1502,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 +1533,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() } : {}),
@@ -2042,7 +2115,8 @@ export class FlowEngine {
     committedDemands() {
         const out = [];
         for (const o of this.orders.values()) {
-            if (o.status === 'completed' || o.status === 'cancelled')
+            /* 같은 판정을 쓴다 — 남은 수요를 세는 자리와 지연을 세는 자리가 다른 규칙을 쓰면 어긋난다. */
+            if (isOrderTerminal(o))
                 continue;
             const remaining = Math.max(0, (o.requested ?? 0) - (o.fulfilled ?? 0));
             if (!remaining)
@@ -3418,7 +3492,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

@@ -56,6 +56,7 @@ __export(index_exports, {
   OPERATION_PROPERTY: () => OPERATION_PROPERTY,
   OP_EVENT: () => OP_EVENT,
   OP_PARAM: () => OP_PARAM,
+  ORDER_TERMINAL_STATUS: () => ORDER_TERMINAL_STATUS,
   ObservedReducer: () => ObservedReducer,
   PRIORITY_UNSET: () => PRIORITY_UNSET,
   RETIRED_VOCABULARY: () => RETIRED_VOCABULARY,
@@ -126,6 +127,7 @@ __export(index_exports, {
   isEnergyRecord: () => isEnergyRecord,
   isEquipmentLevel: () => isEquipmentLevel,
   isOperationalRecord: () => isOperationalRecord,
+  isOrderTerminal: () => isOrderTerminal,
   isTransformationRecord: () => isTransformationRecord,
   isoDurationHours: () => isoDurationHours,
   itemKeyOf: () => itemKeyOf,
@@ -179,6 +181,15 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/contract.ts
+var ORDER_TERMINAL_STATUS = ["completed", "cancelled"];
+function isOrderTerminal(o) {
+  const status = String(o?.status ?? "").trim().toLowerCase();
+  if (ORDER_TERMINAL_STATUS.includes(status)) return true;
+  const requested = o?.requested;
+  const fulfilled = o?.fulfilled;
+  if (typeof requested !== "number" || !(requested > 0)) return false;
+  return typeof fulfilled === "number" && fulfilled >= requested;
+}
 var LOCATION_SATURATION_NEAR = 0.9;
 function locationStatusOf(n) {
   const cap = n.capacity;
@@ -3429,7 +3440,7 @@ function deriveAttentions(view, acked, nowIso, thresholds) {
     });
   }
   for (const o of view.orders) {
-    if (o.status === "completed" || o.status === "fulfilled") continue;
+    if (isOrderTerminal(o)) continue;
     if (dueStatusOf(o, nowIso) !== "late") continue;
     const overdueMs = Date.parse(nowIso) - Date.parse(o.endTime);
     out.push({
@@ -4043,6 +4054,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 +4114,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 +4135,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 +4197,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 +4463,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 +4486,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 +4512,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() } : {},
@@ -4999,7 +5044,7 @@ var FlowEngine = class {
   committedDemands() {
     const out = [];
     for (const o of this.orders.values()) {
-      if (o.status === "completed" || o.status === "cancelled") continue;
+      if (isOrderTerminal(o)) continue;
       const remaining = Math.max(0, (o.requested ?? 0) - (o.fulfilled ?? 0));
       if (!remaining) continue;
       out.push({ remaining, ...o.endTime ? { dueTime: o.endTime } : {} });
@@ -6186,8 +6231,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) {
@@ -8962,6 +9026,7 @@ function retiredVocabularyIn(line) {
   OPERATION_PROPERTY,
   OP_EVENT,
   OP_PARAM,
+  ORDER_TERMINAL_STATUS,
   ObservedReducer,
   PRIORITY_UNSET,
   RETIRED_VOCABULARY,
@@ -9032,6 +9097,7 @@ function retiredVocabularyIn(line) {
   isEnergyRecord,
   isEquipmentLevel,
   isOperationalRecord,
+  isOrderTerminal,
   isTransformationRecord,
   isoDurationHours,
   itemKeyOf,

package/package.json

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