@operato/twin-kernel 0.7.51 → 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

@@ -32,6 +32,50 @@
  * 지키는 하네스: `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.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;
@@ -2113,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)

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({
@@ -5033,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 } : {} });
@@ -9015,6 +9026,7 @@ function retiredVocabularyIn(line) {
   OPERATION_PROPERTY,
   OP_EVENT,
   OP_PARAM,
+  ORDER_TERMINAL_STATUS,
   ObservedReducer,
   PRIORITY_UNSET,
   RETIRED_VOCABULARY,
@@ -9085,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.51",
+  "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": {