@operato/twin-kernel 0.1.0 → 0.2.0

package/dist/forecast.d.ts

@@ -5,6 +5,14 @@ export interface ForecastTwin {
     tick(dtMs: number): void;
     scenario: ScenarioControl;
     fork(): ForecastTwin;
+    /**
+     * 시뮬 시각(ms) — **구동 루프가 시각만 읽을 때 쓰는 값.**
+     *
+     * 없으면 `getSnapshot().simClockMs` 로 떨어지지만, 그 경로는 전 노드·물품·자원·작업·오더를 새로
+     * 재료화하고 주목 신호까지 계산한 뒤 숫자 하나만 꺼내 버린다 — tick 마다 그러면 상태 크기 × 지평선
+     * 길이만큼 낭비가 쌓인다(물품 1만 건·30분 지평선에서 측정: 루프 조건에만 149ms vs 0ms).
+     */
+    clockMs?: number;
 }
 export interface MonteCarloResult {
     runs: number;

package/dist/forecast.js

@@ -5,12 +5,19 @@
  * 관심 지표를 분포로 준다: "언제 끝나?"가 아니라 "P50/P90 완료시각·재고소진 확률".
  * fork(현재예측) + 시나리오 재시드로 미래만 변주 — 현재 상태(재고·오더·태스크)는 보존.
  */
+/**
+ * 구동 루프용 시각 읽기 — **숫자 하나 때문에 전체 상태를 만들지 않는다.**
+ * 커널은 `clockMs` 를 공개하므로 그것을 쓰고, 그것이 없는 외부 구현만 스냅샷으로 떨어진다.
+ */
+function clockOf(twin) {
+    return typeof twin.clockMs === 'number' ? twin.clockMs : twin.getSnapshot().simClockMs;
+}
 /**
  * 현재 상태에서 N개 확률적 미래를 표본화 → 지표 분포.
  * run 마다 fork(현재 보존) + scenario.load(seed+i)(미래 변주) + horizon 까지 구동. 원본 무간섭.
  */
 export function monteCarloForecast(twin, opts) {
-    const now = twin.getSnapshot().simClockMs;
+    const now = clockOf(twin);
     const step = opts.tickMs ?? 1000;
     const baseSeed = opts.scenario.seed ?? 1;
     const samples = [];
@@ -20,7 +27,7 @@ export function monteCarloForecast(twin, opts) {
         fc.scenario.start();
         const target = now + opts.horizonMs;
         let guard = 0;
-        while (fc.getSnapshot().simClockMs < target && guard++ < 1_000_000)
+        while (clockOf(fc) < target && guard++ < 1_000_000)
             fc.tick(step);
         samples.push(opts.metric(fc.getSnapshot()));
     }

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from './capability.ts';
 export * from './domain-catalog.ts';
 export * from './allocation-policy.ts';
 export * from './duration-estimator.ts';
+export * from './iso-duration.ts';
 export * from './state-projector.ts';
 export * from './task-fold.ts';
 export * from './face2-adapter.ts';

package/dist/index.js

@@ -11,6 +11,7 @@ export * from "./capability.js";
 export * from "./domain-catalog.js";
 export * from "./allocation-policy.js";
 export * from "./duration-estimator.js";
+export * from "./iso-duration.js";
 export * from "./state-projector.js";
 export * from "./task-fold.js";
 export * from "./face2-adapter.js";

package/dist/iso-duration.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ISO 8601 기간 → 밀리초. 해석할 수 없으면 **undefined**(0 이 아니다 — "0초" 와 "모른다" 는 다르다).
+ * 연·월(`Y`·`P…M` 의 날짜부 M)은 달력 의존이라 거부한다.
+ */
+export declare function parseIsoDuration(text?: string): number | undefined;

package/dist/iso-duration.js

@@ -0,0 +1,43 @@
+/*
+ * ISO 8601 기간 파서 — **표준 표기를 그대로 받기 위한 최소 도구.**
+ *
+ * ISA-95 의 `OperationsSegment.Duration` 은 `xsd:duration` 이다(B2MML `DurationType` =
+ * `<xsd:restriction base="xsd:duration"/>`). 그래서 명세가 말하는 소요시간은 `PT12M`·`PT1H15M`
+ * 같은 문자열로 온다 — 우리가 숫자 밀리초로 바꿔 부르는 순간 표준과 어긋나므로, **계약은 표준 표기로
+ * 받고 여기서 한 번만 해석한다**(소비처가 문자열을 자르지 않게).
+ *
+ * 지원 범위: `PnYnMnWnDTnHnMnS` 의 주·일·시·분·초(소수 초 포함). **연·월은 거부한다** —
+ * 길이가 달력에 따라 달라져 밀리초로 확정할 수 없다(28~31일). 모르면 꾸미지 않고 undefined 를 낸다.
+ */
+const RE = /^(-)?P(?:(\d+(?:\.\d+)?)W)?(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+/**
+ * ISO 8601 기간 → 밀리초. 해석할 수 없으면 **undefined**(0 이 아니다 — "0초" 와 "모른다" 는 다르다).
+ * 연·월(`Y`·`P…M` 의 날짜부 M)은 달력 의존이라 거부한다.
+ */
+export function parseIsoDuration(text) {
+    if (typeof text !== 'string')
+        return undefined;
+    const s = text.trim();
+    if (!s || s === 'P' || s === 'PT')
+        return undefined;
+    if (/\d+Y/.test(s))
+        return undefined; // 연 — 달력 의존
+    /* 날짜부의 M(월)과 시간부의 M(분)을 구별한다: T 앞의 M 은 월이므로 거부. */
+    const tIdx = s.indexOf('T');
+    const datePart = tIdx === -1 ? s : s.slice(0, tIdx);
+    if (/\d+M/.test(datePart))
+        return undefined; // 월 — 달력 의존
+    const m = RE.exec(s);
+    if (!m)
+        return undefined;
+    const [, sign, w, d, h, min, sec] = m;
+    if (!w && !d && !h && !min && !sec)
+        return undefined;
+    const ms = (Number(w ?? 0) * 7 + Number(d ?? 0)) * 86_400_000 +
+        Number(h ?? 0) * 3_600_000 +
+        Number(min ?? 0) * 60_000 +
+        Number(sec ?? 0) * 1000;
+    if (!Number.isFinite(ms))
+        return undefined;
+    return sign ? -ms : ms;
+}

package/dist/kernel.js

@@ -9,7 +9,7 @@ import { CMD } from "./contract.js";
 import { firstFitPolicy } from "./allocation-policy.js";
 import { FlowEngine } from "./flow-engine.js";
 import { BIZSTEP, BTT } from "./wms-profile.js";
-import { DISP, aggregationEvent, gdtiUri, objectEvent, ssccUri, transactionEvent } from "./epcis.js";
+import { DISP, ILMD_ATTR, aggregationEvent, gdtiUri, objectEvent, ssccUri, transactionEvent } from "./epcis.js";
 const TRAVEL_MS = 30_000;
 const COMPANY_PREFIX = '0614141';
 const SHELF_MS = 30 * 24 * 3_600_000; // 기본 유통기한(30일)
@@ -37,7 +37,13 @@ export class WmsKernel extends FlowEngine {
         dock.occupancy++;
         this.emit(transactionEvent({ eventTime, action: 'ADD', bizStep: BIZSTEP.receiving, bizTransactionList: poTxn, epcList: [epc], quantityList: qtyList, readPoint: dock.id }));
         this.emit(aggregationEvent({ eventTime, action: 'ADD', bizStep: BIZSTEP.receiving, parentID: epc, childQuantityList: qtyList, readPoint: dock.id }));
-        this.emit(objectEvent({ eventTime, action: 'ADD', bizStep: BIZSTEP.receiving, disposition: DISP.in_progress, epcList: [epc], quantityList: qtyList, readPoint: dock.id, bizLocation: dock.id, bizTransactionList: poTxn }));
+        /* 만료는 이 팔레트가 **생겨나는 순간** 정해지는 태생 속성이라 개체·로트 마스터데이터로 싣는다
+         * (§7.3.8: ObjectEvent action=ADD 에만 허용). 예전에는 커널 내부 상태에만 두어 미러가 알 수 없었다. */
+        this.emit(objectEvent({
+            eventTime, action: 'ADD', bizStep: BIZSTEP.receiving, disposition: DISP.in_progress,
+            epcList: [epc], quantityList: qtyList, readPoint: dock.id, bizLocation: dock.id, bizTransactionList: poTxn,
+            ilmd: { [ILMD_ATTR.expiry]: expiry }
+        }));
         const binId = this.policy.selectPlacement({ item: { epc, gtin, qty }, slots: this.slotViews('storage') });
         if (!binId)
             return; // 수용 불가 → 도크 대기

package/dist/mes-kernel.d.ts

@@ -2,7 +2,7 @@ import type { GeneratorSpec, Command, CommandAck } from './contract.ts';
 import type { AllocationPolicy } from './allocation-policy.ts';
 import { FlowEngine } from './flow-engine.ts';
 import type { FlowOrder, FlowTask } from './flow-engine.ts';
-import type { DomainDefinition } from './domain-definition.ts';
+import { type DomainDefinition } from './domain-definition.ts';
 /** 편의 — 시나리오 skuMix 로 쓸 부품 클래스. */
 export declare const MES_PART_GTINS: {
     partA: string;
@@ -40,7 +40,7 @@ export declare class MesKernel extends FlowEngine {
     /**
      * MES 도메인 커맨드(Tier 2) — mes.changeover: 설비를 제품 gtin 으로 강제 전환.
      * 자동 체인지오버(task.changeoverKey 상이 시 셋업)의 수동 버전 — 운영자가 사전 전환(툴링 교체) 지시.
-     * 이미 그 제품이면 no-op, 아니면 셋업(SETUP_MS, OEE 가용성 손실) + lastChangeoverKey 각인
+     * 이미 그 제품이면 no-op, 아니면 셋업(기본값, OEE 가용성 손실) + lastChangeoverKey 각인
      * (이후 그 제품 task 는 자동 셋업 생략). command → 변이 → State 델타(폐루프).
      */
     protected handleCommand(cmd: Command): CommandAck;

package/dist/mes-kernel.js

@@ -12,14 +12,18 @@ import { firstFitPolicy } from "./allocation-policy.js";
 import { FlowEngine } from "./flow-engine.js";
 import { DISP, objectEvent, transactionEvent, gdtiUri, sgtinClass } from "./epcis.js";
 import { MES_BIZSTEP, BTT_PRODORDER, sgtinUri } from "./mes-profile.js";
-const CYCLE_MS = 40_000;
-const SETUP_MS = 15_000; // 체인지오버(제품 전환) 셋업 — OEE 가용성 손실
+import { OP_PARAM } from "./domain-definition.js";
+/* 아래 셋은 **기본값**이다 — 명세(OperationDef.duration·parameters)가 있으면 그 값이 이긴다.
+ * 이름에 DEFAULT 를 붙인 이유: 예전에는 이것이 유일한 값이어서 "현장 명세" 와 구별되지 않았고,
+ * 그 상수가 수율 판단(주목 신호)까지 만들어 냈다. 무엇을 기본값으로 굴렸는지는 specCoverage() 가 밝힌다. */
+const DEFAULT_CYCLE_MS = 40_000;
+const DEFAULT_SETUP_MS = 15_000; // 체인지오버(제품 전환) 셋업 — OEE 가용성 손실
 // MES 도메인 커맨드(Tier 2, 무방언 — MES 어휘는 MES 커널 소유). handleCommand 로 처리.
 const MES_CMD = { changeover: 'mes.changeover' };
 const CP = '0614141';
 const WIP_ITEMREF = '066666';
 const WIP_GTIN = sgtinClass(CP, WIP_ITEMREF);
-const YIELD = 0.8; // 양품률 — 나머지는 불량(non_sellable) → OEE 품질 손실
+const DEFAULT_YIELD = 0.8; // 양품률 기본값 — 현장 값은 OperationDef.parameters(OP_PARAM.yield) 로 온다
 // 부품(공용) — BOM 라인의 품목 클래스.
 const PART_A = { itemRef: '055551', gtin: sgtinClass(CP, '055551') };
 const PART_B = { itemRef: '055552', gtin: sgtinClass(CP, '055552') };
@@ -53,12 +57,15 @@ export class MesKernel extends FlowEngine {
     constructor(tenantId, policy = firstFitPolicy, mesSpec) {
         super(tenantId, policy);
         this.mesSpec = mesSpec;
+        /* 정의가 있으면 그 안의 오퍼레이션 명세(소요·변동·모수)를 커널이 소비한다 — 없으면 기본값 경로. */
+        if (mesSpec?.definition?.operations)
+            this.loadOperations(mesSpec.definition.operations);
     }
     productOf(gtin) { return PRODUCTS.find(p => p.gtin === gtin); }
     /**
      * MES 도메인 커맨드(Tier 2) — mes.changeover: 설비를 제품 gtin 으로 강제 전환.
      * 자동 체인지오버(task.changeoverKey 상이 시 셋업)의 수동 버전 — 운영자가 사전 전환(툴링 교체) 지시.
-     * 이미 그 제품이면 no-op, 아니면 셋업(SETUP_MS, OEE 가용성 손실) + lastChangeoverKey 각인
+     * 이미 그 제품이면 no-op, 아니면 셋업(기본값, OEE 가용성 손실) + lastChangeoverKey 각인
      * (이후 그 제품 task 는 자동 셋업 생략). command → 변이 → State 델타(폐루프).
      */
     handleCommand(cmd) {
@@ -70,7 +77,9 @@ export class MesKernel extends FlowEngine {
             if (!m)
                 return { commandId: cmd.commandId, accepted: false, errorCode: 'resource-not-found', errorParams: { resourceId: a.resourceId }, error: `resource-not-found: ${a.resourceId}` };
             if (m.lastChangeoverKey !== a.gtin) {
-                m.setupMs += SETUP_MS; // 셋업 = OEE 가용성 손실
+                /* 수동 전환은 특정 오퍼레이션이 아니라 설비 대상이라 작업별 명세를 고를 수 없다 → 기본값.
+                 * 오퍼레이션별 셋업 명세는 작업 생성 경로(emitStation*)가 소비한다. */
+                m.setupMs += DEFAULT_SETUP_MS; // 셋업 = OEE 가용성 손실
                 m.lastChangeoverKey = a.gtin;
                 this.emitMover(m);
             }
@@ -137,7 +146,7 @@ export class MesKernel extends FlowEngine {
     /** 라우트 스테이션 태스크 발행(공통) — 제자리 가공(process), 이종 자원, 제품 전환 셋업. */
     emitStation(o, stage, itemEpc, changeoverKey) {
         const node = this.nodeByType(stage.node);
-        const task = { id: `task-${++this.taskSeq}`, kind: stage.kind, status: 'created', itemEpc, fromNode: node.id, toNode: node.id, resource: null, remainingMs: 0, durationMs: this.durationOf({ kind: stage.kind, fromNode: node.id, toNode: node.id, resourceKind: stage.resource }, CYCLE_MS), orderId: o.id, resourceType: stage.resource, changeoverKey, setupMs: SETUP_MS, intent: 'process' };
+        const task = { id: `task-${++this.taskSeq}`, kind: stage.kind, status: 'created', itemEpc, fromNode: node.id, toNode: node.id, resource: null, remainingMs: 0, durationMs: this.durationOf({ kind: stage.kind, fromNode: node.id, toNode: node.id, resourceKind: stage.resource }, DEFAULT_CYCLE_MS), orderId: o.id, resourceType: stage.resource, changeoverKey, setupMs: this.paramDuration(stage.kind, OP_PARAM.setupDuration) ?? DEFAULT_SETUP_MS, intent: 'process' };
         this.tasks.set(task.id, task);
         this.emitTask(task);
     }
@@ -165,7 +174,7 @@ export class MesKernel extends FlowEngine {
         // 마지막 스테이션(조립) → 완성차 (transform 1→1, disposition 으로 수율 loss → OEE 품질)
         const fgStore = this.nodeByType('fg-store');
         const wip = order.allocated[0];
-        const good = this.rng() < YIELD;
+        const good = this.rng() < (this.paramNumber(t.kind, OP_PARAM.yield) ?? DEFAULT_YIELD);
         this.recordOutput(t.resource, good); // OEE 품질(마지막 자원별 양품/불량)
         const disp = good ? DISP.sellable : DISP.non_sellable;
         const outputEpc = sgtinUri(CP, product.ref, ++this.prodSeq);
@@ -245,7 +254,7 @@ export class MesKernel extends FlowEngine {
     }
     emitStationDef(o, op, itemEpc) {
         const node = this.nodeByType(op.nodeType);
-        const task = { id: `task-${++this.taskSeq}`, kind: op.key, status: 'created', itemEpc, fromNode: node.id, toNode: node.id, resource: null, remainingMs: 0, durationMs: this.durationOf({ kind: op.key, fromNode: node.id, toNode: node.id, resourceKind: op.resourceType }, CYCLE_MS), orderId: o.id, resourceType: op.resourceType, changeoverKey: o.gtin, setupMs: SETUP_MS, intent: op.intent };
+        const task = { id: `task-${++this.taskSeq}`, kind: op.key, status: 'created', itemEpc, fromNode: node.id, toNode: node.id, resource: null, remainingMs: 0, durationMs: this.durationOf({ kind: op.key, fromNode: node.id, toNode: node.id, resourceKind: op.resourceType }, DEFAULT_CYCLE_MS), orderId: o.id, resourceType: op.resourceType, changeoverKey: o.gtin, setupMs: this.paramDuration(op.key, OP_PARAM.setupDuration) ?? DEFAULT_SETUP_MS, intent: op.intent };
         this.tasks.set(task.id, task);
         this.emitTask(task);
     }
@@ -272,7 +281,7 @@ export class MesKernel extends FlowEngine {
         }
         const fgStore = this.nodeByType('fg-store');
         const wip = order.allocated[0];
-        const good = this.rng() < YIELD;
+        const good = this.rng() < (this.paramNumber(t.kind, OP_PARAM.yield) ?? DEFAULT_YIELD);
         this.recordOutput(t.resource, good);
         const disp = good ? DISP.sellable : DISP.non_sellable;
         const outEpc = this.serialOf(rc.outputs[0].material, ++this.prodSeq);

package/dist/state-projector.d.ts

@@ -1,35 +1,98 @@
-import type { BoardDef, CanonicalEnvelope, NodeState, ItemState, MoverState, TaskState, OrderState } from './contract.ts';
-/** 마스터 동기 — 선언적 로케이션 upsert/remove (실 소스 연동은 host 계층 Face2 커넥터). */
+import type { AssetState, BoardDef, CanonicalEnvelope, NodeState, ItemState, MoverState, PersonState, TaskState, OrderState } from './contract.ts';
+/**
+ * 마스터 동기 — 선언적 로케이션 upsert/remove.
+ *
+ * 구조(로케이션·용량·구역 소속)는 이벤트가 말해 주는 것이 아니라 **원 시스템의 마스터**에서 온다.
+ * 최초 생성은 Face2 마스터 인제스트(host `ingestMaster`)가 하고, 그 뒤 현장이 바뀐 것(랙 증설·구역
+ * 재편·용량 변경)은 이 경로로 **기동 중에도** 반영된다 — 없으면 재기동해야 구조가 갱신된다.
+ */
 export interface MasterUpdate {
     op: 'upsert' | 'remove';
     node: {
         id: string;
         type?: string;
         capacity?: number;
+        parentId?: string;
     };
 }
 export interface ProjectedState {
     revision: number;
+    /**
+     * 받은 정정 선언들 — 상태에 반영하지 않은 것을 **밝힌다**.
+     * 비어 있지 않으면 "원 시스템이 정정을 보냈고 우리는 아직 반영하지 못했다" 는 뜻이다(조용한 무시 금지).
+     */
+    corrections?: {
+        declaredAt: string;
+        reason?: string;
+        correctiveEventIDs: string[];
+        eventID?: string;
+    }[];
     nodes: NodeState[];
     items: ItemState[];
+    /** 사람 — 등급·교대·투입. 인원을 선언하지 않은 트윈에서는 빈 배열. */
+    persons: PersonState[];
+    /** 물리 자산(반복사용) — 자산을 선언하지 않은 트윈에서는 빈 배열. */
+    assets: AssetState[];
     tasks: TaskState[];
     movers: MoverState[];
     orders: OrderState[];
 }
 export declare class StateProjector {
+    /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
     private master;
     private items;
     private aggregation;
     private tasks;
     private movers;
+    private persons;
+    private assets;
     private orders;
     revision: number;
+    /** 받은 정정 선언 — 상태에 반영하지 않되 **버리지도 않는다**(소비처가 볼 수 있게). */
+    private corrections;
     constructor(board: BoardDef);
     /** 마스터 동기 — 로케이션 추가/변경/제거. */
     applyMaster(u: MasterUpdate): void;
+    /**
+     * 관측된 로케이션을 구조로 승격 — **이벤트가 가르쳐 준 것을 구조에서 지우지 않는다.**
+     *
+     * 마스터에 없는 로케이션에서 물품이 관측되면, 예전에는 물품의 `location` 에만 남고 `nodes` 에는
+     * 나타나지 않았다. 그 결과 그 자리는 스키매틱에 없고, 점유가 집계되지 않고, 병목 주목이 뜰 수
+     * 없었다 — **사실은 들어왔는데 구조가 모르는 상태.** 이제 최소 형태로 승격한다:
+     * 종류는 모르므로 `unknown`, **용량은 비워 둔다**(발명하지 않는다), 출처는 `observed`.
+     *
+     * 출처를 표시하는 이유: 소비처가 "마스터가 말한 자리" 와 "관측으로 알게 된 자리" 를 구별해야 한다
+     * (보드에 좌표가 없고, 용량을 채워야 계획에 참여한다). 마스터 동기가 오면 `master` 로 승격된다.
+     */
+    private touchLocation;
+    /**
+     * 늦게 도착한 옛 이벤트를 걸러낸다 — **도착 순서 ≠ 발생 순서**.
+     *
+     * 실 연동에서는 순서가 뒤집힌다(재시도·큐·배치). 시각을 비교하지 않으면 **늦게 온 옛 이벤트가 최신
+     * 상태를 덮어써** 위치가 과거로 튄다. 표준이 발생(`eventTime`)과 기록(`recordTime`)을 나눠 둔 이유가
+     * 이것이므로, 대상별로 마지막으로 반영한 시각을 기억해 그보다 오래된 것은 무시한다.
+     *
+     * 판정 시각은 **발생 시각**을 쓴다(현장에서 일어난 순서가 사실). `recordTime` 은 같은 발생 시각이
+     * 겹칠 때의 보조 기준이다. 시각이 없으면 판정하지 않는다(있는 것만 가지고 판단한다).
+     */
+    private stale;
+    /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
+    private lastAt;
     /** 이벤트 1건 반영 — eventType 으로 EPCIS vs 운영 델타 분기. */
     apply(e: CanonicalEnvelope): void;
     private applyEpcis;
+    /**
+     * 물품 한 건 병합 — **아는 것을 잃지 않는다.** 새로 온 값이 우선, 없으면 기존 값 유지.
+     * 클래스 식별자(LGTIN/idpat)에서 품번·로트를 파생한다 — 소비처가 문자열을 자르지 않게.
+     */
+    /**
+     * 개체·로트 마스터데이터에서 만료 시각을 뽑는다 — **우리가 아는 이름일 때만.**
+     *
+     * 표준이 속성 이름을 정의하지 않으므로 모르는 이름은 해석하지 않는다(추측하지 않는다). 원문은
+     * `ilmd` 로 그대로 남으니 도메인이 자기 어휘로 읽을 수 있다.
+     */
+    private expiryOf;
+    private mergeItem;
     /** 이탈(DELETE) — 아이템 + 조립 자식(재귀) 제거. 화물 SSCC DELETE 시 팔레트도 함께 이탈. */
     private remove;
     /** 현재 투영 State — 노드 점유는 아이템 위치 집계로 유도(pure projection). */