@operato/twin-kernel 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -15,11 +15,13 @@ export * from './iso-duration.ts';
 export * from './observed-reducer.ts';
 export * from './state-projector.ts';
 export * from './task-fold.ts';
+export * from './job-response.ts';
 export * from './face2-adapter.ts';
 export * from './runtime.ts';
 export * from './yms-profile.ts';
 export * from './mes-profile.ts';
 export * from './flow-engine.ts';
+export * from './capacity.ts';
 export { WmsKernel } from './kernel.ts';
 export { YmsKernel } from './yms-kernel.ts';
 export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from './mes-kernel.ts';

package/dist/index.js

@@ -15,11 +15,13 @@ export * from "./iso-duration.js";
 export * from "./observed-reducer.js";
 export * from "./state-projector.js";
 export * from "./task-fold.js";
+export * from "./job-response.js";
 export * from "./face2-adapter.js";
 export * from "./runtime.js";
 export * from "./yms-profile.js";
 export * from "./mes-profile.js";
 export * from "./flow-engine.js";
+export * from "./capacity.js";
 export { WmsKernel } from "./kernel.js";
 export { YmsKernel } from "./yms-kernel.js";
 export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from "./mes-kernel.js";

package/dist/job-response.d.ts

@@ -0,0 +1,59 @@
+import type { ISOTime } from './contract.ts';
+import { type TaskDeltaRow } from './task-fold.ts';
+/** 표준 `JobState` — 우리 작업 상태를 표준 낱말로 옮긴다. */
+export type JobState = 'ready' | 'running' | 'completed';
+/** 자원 실적 한 줄 — 표준 `OpPersonnelActualType`/`OpEquipmentActualType` 의 우리 부분집합. */
+export interface ResourceActual {
+    /** 표준 `PersonID`/`EquipmentID`. */
+    id: string;
+    /** 표준 `Quantity`. 우리는 개체를 지목하므로 언제나 1이다(등급 단위 집계는 소비처의 일). */
+    quantity: number;
+}
+/** 자재 실적 한 줄 — 표준 `OpMaterialActualType` 의 우리 부분집합. */
+export interface MaterialActual {
+    /** 표준 `MaterialDefinitionID`. */
+    definitionId: string;
+    /** 표준 `MaterialUse`. */
+    use: 'consumed' | 'produced';
+    quantity: number;
+    uom?: string;
+}
+export interface JobResponse {
+    /** 표준 `ID` — 작업 식별자. */
+    id: string;
+    /** 표준 `JobOrderID` — 소속 오더. **없으면 없는 것이다**(다른 식별자로 대체하지 않는다). */
+    jobOrderId?: string;
+    /** 표준 `WorkType` — 작업 종류(우리 `kind`). */
+    workType?: string;
+    /** 표준 `JobState`. */
+    jobState: JobState;
+    /** 표준 `StartTime` — **실제** 착수. 착수 기록을 못 찾으면 없다(짐작하지 않는다). */
+    startTime?: ISOTime;
+    /** 표준 `EndTime` — **실제** 완료. */
+    endTime?: ISOTime;
+    /** 표준 `PersonnelActual`. */
+    personnelActual?: ResourceActual[];
+    /** 표준 `EquipmentActual`. */
+    equipmentActual?: ResourceActual[];
+    /**
+     * 표준 `PhysicalAssetActual` — **실제로 쓰인 반복사용 자산**(팔레트·용기 등).
+     *
+     * 작업이 이미 들고 있던 사실인데 실적에서 빠져 있었다. 빠지면 "그 출고에 팔레트 몇 장이 나갔나" 를
+     * 실적으로 답할 수 없고, 자산 회수 계획이 근거를 잃는다.
+     */
+    physicalAssetActual?: ResourceActual[];
+    /** 표준 `MaterialActual`. */
+    materialActual?: MaterialActual[];
+}
+/** 저널 한 줄에서 자원·자재 실적을 읽기 위한 최소 모양(작업 폴드가 보는 것과 같은 줄). */
+type Row = TaskDeltaRow;
+/**
+ * 저널을 접어 **작업별 실적 회신**을 만든다 — 표준 이름으로.
+ *
+ * 짝맞춤(어느 전이가 한 작업인가)은 **커널 규칙**(`foldTaskRecords`)을 그대로 쓴다. 여기서 다시 짝을
+ * 맞추면 같은 저널이 지표에서는 3건, 실적에서는 4건이 되는 일이 생긴다 — 실제로 겪은 부류다.
+ *
+ * 자원·자재 실적은 전이가 실어 온 값에서 모은다. **마지막에 본 값**이 사실이다(재전송이면 나중 것).
+ */
+export declare function foldJobResponses(rows: readonly Row[]): JobResponse[];
+export {};

package/dist/job-response.js

@@ -0,0 +1,56 @@
+import { foldTaskRecords } from "./task-fold.js";
+const iso = (ms) => (typeof ms === 'number' ? new Date(ms).toISOString() : undefined);
+const dataOf = (r) => {
+    const p = r.payload;
+    return r.data ?? p?.data ?? p ?? {};
+};
+/**
+ * 저널을 접어 **작업별 실적 회신**을 만든다 — 표준 이름으로.
+ *
+ * 짝맞춤(어느 전이가 한 작업인가)은 **커널 규칙**(`foldTaskRecords`)을 그대로 쓴다. 여기서 다시 짝을
+ * 맞추면 같은 저널이 지표에서는 3건, 실적에서는 4건이 되는 일이 생긴다 — 실제로 겪은 부류다.
+ *
+ * 자원·자재 실적은 전이가 실어 온 값에서 모은다. **마지막에 본 값**이 사실이다(재전송이면 나중 것).
+ */
+export function foldJobResponses(rows) {
+    const { records } = foldTaskRecords(rows);
+    /* 자원·자재는 작업 폴드가 모으는 축(facets) 밖이라 여기서 한 번 더 훑는다 — 작업 폴드의 뜻을
+       넓히지 않는다(그것은 "언제" 를 아는 모듈이고, 이것은 "무엇으로" 를 아는 모듈이다). */
+    const extra = new Map();
+    for (const r of rows) {
+        const d = dataOf(r);
+        const id = typeof d.taskId === 'string' ? d.taskId : undefined;
+        if (!id)
+            continue;
+        const cur = extra.get(id) ?? {};
+        if (Array.isArray(d.personnel))
+            cur.personnel = d.personnel;
+        /* 대표 자원 하나만 온 전이도 있다(`resourceRef`) — 함께 잡힌 목록이 있으면 그것이 더 완전하다. */
+        if (Array.isArray(d.resources))
+            cur.resources = d.resources;
+        else if (typeof d.resourceRef === 'string' && !cur.resources)
+            cur.resources = [d.resourceRef];
+        if (Array.isArray(d.assets))
+            cur.assets = d.assets;
+        if (Array.isArray(d.materialActual))
+            cur.material = d.materialActual;
+        extra.set(id, cur);
+    }
+    return records.map(rec => {
+        const x = extra.get(rec.taskId) ?? {};
+        const jobState = rec.completedMs !== undefined ? 'completed' : rec.startedMs !== undefined ? 'running' : 'ready';
+        const one = (ids) => ids?.length ? ids.map(id => ({ id, quantity: 1 })) : undefined;
+        return {
+            id: rec.taskId,
+            ...(rec.facets.order ? { jobOrderId: rec.facets.order } : {}),
+            ...(rec.facets.kind ? { workType: rec.facets.kind } : {}),
+            jobState,
+            ...(iso(rec.startedMs) ? { startTime: iso(rec.startedMs) } : {}),
+            ...(iso(rec.completedMs) ? { endTime: iso(rec.completedMs) } : {}),
+            ...(one(x.personnel) ? { personnelActual: one(x.personnel) } : {}),
+            ...(one(x.resources) ? { equipmentActual: one(x.resources) } : {}),
+            ...(one(x.assets) ? { physicalAssetActual: one(x.assets) } : {}),
+            ...(x.material?.length ? { materialActual: x.material.map(m => ({ ...m })) } : {})
+        };
+    });
+}

package/dist/kernel.d.ts

@@ -14,6 +14,11 @@ export declare class WmsKernel extends FlowEngine {
     protected onOrder(spec: GeneratorSpec): void;
     /** Command 채널 — 오더 즉시 투입(트랜잭션 프론트엔드/prescriptive). */
     protected handleCommand(cmd: Command): CommandAck;
+    /**
+     * 오더 생성 — 약속(`promised`)이 있으면 **납기와 우선순위를 함께 싣는다**(표준 `EndTime`·`Priority`).
+     * 없으면 싣지 않는다: 없는 약속을 만들면 그 뒤 모든 지연 판정이 거짓 위에 선다.
+     */
+    /** 오더 생성 — 약속(납기·우선순위)은 base `promiseOf` 가 계산한다(도메인마다 다르게 재지 않는다). */
     private createSalesOrder;
     /**
      * created 오더를 정책으로 할당 → SO TransactionEvent(라인 통합) + pick task(라인별).

package/dist/kernel.js

@@ -26,6 +26,9 @@ export class WmsKernel extends FlowEngine {
             return;
         const epc = ssccUri(COMPANY_PREFIX, ++this.epcSeq); // 팔레트 SSCC
         const gtin = this.pickGtin(spec.content.skuMix); // SGTIN idpat = epcClass
+        /* 품목 구성이 비어 있으면 **도착을 만들지 않는다** — 무엇이 왔는지 말할 수 없는 입고는 사실이 아니다. */
+        if (!gtin)
+            return;
         const qty = this.randInt(spec.content.qtyPerLine.min, spec.content.qtyPerLine.max); // 케이스 수(비직렬)
         const po = gdtiUri(COMPANY_PREFIX, '401', ++this.poSeq);
         const eventTime = this.now();
@@ -62,7 +65,10 @@ export class WmsKernel extends FlowEngine {
     onOrder(spec) {
         const lpl = spec.content.linesPerOrder;
         if (!lpl) {
-            this.createSalesOrder([{ gtin: this.pickGtin(spec.content.skuMix), qty: this.randInt(spec.content.qtyPerLine.min, spec.content.qtyPerLine.max) }]);
+            const only = this.pickGtin(spec.content.skuMix);
+            if (!only)
+                return; // 품목 구성이 없으면 오더도 없다(무엇을 달라는 오더인지 말할 수 없다)
+            this.createSalesOrder([{ gtin: only, qty: this.randInt(spec.content.qtyPerLine.min, spec.content.qtyPerLine.max) }], spec);
             return;
         }
         const n = Math.min(this.randInt(lpl.min, lpl.max), spec.content.skuMix.length);
@@ -70,10 +76,14 @@ export class WmsKernel extends FlowEngine {
         let pool = spec.content.skuMix;
         for (let i = 0; i < n && pool.length > 0; i++) {
             const gtin = this.pickGtin(pool);
+            if (!gtin)
+                break;
             lines.push({ gtin, qty: this.randInt(spec.content.qtyPerLine.min, spec.content.qtyPerLine.max) });
             pool = pool.filter(m => m.gtin !== gtin); // 라인 SKU 중복 방지(distinct)
         }
-        this.createSalesOrder(lines);
+        if (!lines.length)
+            return; // 라인이 하나도 안 나오면 오더를 만들지 않는다
+        this.createSalesOrder(lines, spec);
     }
     /** Command 채널 — 오더 즉시 투입(트랜잭션 프론트엔드/prescriptive). */
     handleCommand(cmd) {
@@ -87,13 +97,19 @@ export class WmsKernel extends FlowEngine {
         }
         return super.handleCommand(cmd);
     }
-    createSalesOrder(lines) {
+    /**
+     * 오더 생성 — 약속(`promised`)이 있으면 **납기와 우선순위를 함께 싣는다**(표준 `EndTime`·`Priority`).
+     * 없으면 싣지 않는다: 없는 약속을 만들면 그 뒤 모든 지연 판정이 거짓 위에 선다.
+     */
+    /** 오더 생성 — 약속(납기·우선순위)은 base `promiseOf` 가 계산한다(도메인마다 다르게 재지 않는다). */
+    createSalesOrder(lines, spec) {
         const id = `order-${++this.orderSeq}`;
         const so = gdtiUri(COMPANY_PREFIX, '402', ++this.soSeq);
         const requested = lines.reduce((s, l) => s + l.qty, 0);
         const order = {
             id, kind: 'outbound', status: 'created', requested, fulfilled: 0, bizTransaction: so,
-            allocated: [], picked: [], shipmentEpc: null, lines: lines.map(l => ({ gtin: l.gtin, requested: l.qty }))
+            allocated: [], picked: [], shipmentEpc: null, lines: lines.map(l => ({ gtin: l.gtin, requested: l.qty })),
+            ...(spec ? this.promiseOf(spec) : {})
         };
         this.orders.set(id, order);
         this.emitOrder(order);
@@ -140,7 +156,11 @@ export class WmsKernel extends FlowEngine {
     }
     /** 태스크 완료 — 이동 반영 후 putaway=storing, pick=picking(+전량 시 pack→stage→ship). */
     onTaskComplete(t) {
-        const item = this.items.get(t.itemEpc);
+        const item = this.itemByRef(t.itemEpc);
+        /* 여기 도달했다면 코어가 이미 물품을 확인했다(주체가 사라진 작업은 완료 전에 접힌다).
+           그래도 단정(`!`)은 쓰지 않는다 — 계약이 바뀌면 조용히 틀리는 대신 분명히 멈춘다. */
+        if (!item)
+            throw new Error(`task ${t.id}: item "${t.itemEpc}" vanished between the core check and the domain hook`);
         const from = this.locations.get(t.fromNode);
         const to = this.locations.get(t.toNode);
         from.occupancy--;

package/dist/mes-kernel.d.ts

@@ -36,6 +36,19 @@ export declare class MesKernel extends FlowEngine {
     /** 정의-구동 모드(선택). 미지정 시 레거시 하드코딩 경로 — byte-identical. */
     private mesSpec?;
     constructor(tenantId: string, policy?: AllocationPolicy, mesSpec?: MesDefinitionSpec);
+    /**
+     * **산출을 두 곳에서 만들지 않는다** — 기동 때 막는다.
+     *
+     * MES 는 레시피로 산출을 만든다: WIP 사슬(스텝마다 앞의 WIP 을 먹고 다음 WIP 을 낸다) · **직렬번호**
+     * (회사 프리픽스 + 일련번호) · **수율**(양품/불량이 처분을 가른다) · 생산오더 연결. 코어의 일반
+     * 자재 명세(`use: 'produced'`)는 **비직렬 클래스+수량**이라 그 넷을 표현하지 못한다.
+     *
+     * 그래서 MES 를 일반 선언으로 옮기지 않는다 — 옮기면 정체성·수율·오더 연결을 **잃는다**(§4-20).
+     * 대신 둘이 겹치면 **같은 산출을 두 번 만들게** 되므로, 그 조합을 기동 시점에 거부한다.
+     * 런타임에 조용히 두 배가 되는 것보다 기동이 실패하는 편이 낫다(재고가 거짓이 되면 그 위의
+     * 모든 계산이 거짓이 된다).
+     */
+    private assertNoDoubleProduction;
     private productOf;
     /**
      * MES 도메인 커맨드(Tier 2) — mes.changeover: 설비를 제품 gtin 으로 강제 전환.
@@ -53,11 +66,26 @@ export declare class MesKernel extends FlowEngine {
     /** 라우트 스테이션 태스크 발행(공통) — 제자리 가공(process), 이종 자원, 제품 전환 셋업. */
     private emitStation;
     /** op 완료 = 변환. 라우트 인덱스로 분기: 첫=BOM 소비→WIP, 중간=WIP→WIP, 마지막(조립)=WIP→완성차(수율→OEE 품질). */
+    /**
+     * MES 는 완료 시점에 **오더와 제품 정의**를 딛고 선다 — 둘 중 하나만 없어도 끝맺을 수 없다.
+     *
+     * 씨앗이 이미 이행된 오더를 심지 않으므로(남은 수량 0) 그 오더에 딸린 작업만 남을 수 있고,
+     * 관측이 오더 연결을 담지 못한 작업도 있다. 그때 예전에는 `order.gtin` 에서 던졌고 **그 예외
+     * 하나가 정확도 추세 전체를 죽였다.** 이제 코어가 이 답을 보고 그 작업만 접는다.
+     */
+    protected canComplete(t: FlowTask): boolean;
     protected onTaskComplete(t: FlowTask): void;
     private recipeDef;
     /** 자재 키 → 구체 gtin 클래스(idpat). 구체 식별은 바인딩+prefix 로 인스턴스가 주입. */
     private classOf;
     private serialOf;
+    /**
+     * 라우트를 용량 계산에 알려 준다 — 수율을 거슬러 올릴 때 순서가 곧 계산이다.
+     *
+     * 순서를 모르면 선언 순서대로 세는데, 그러면 하류에서 잃는 몫이 엉뚱한 공정에 얹힌다(조용히
+     * 틀린다). 생산 정의를 가진 커널만 이 답을 안다.
+     */
+    protected routeKeys(): string[] | undefined;
     /** recipe.route → 오퍼레이션 시퀀스 해소. */
     private routeOps;
     /** 정의 모드 수령 — skuMix gtin 이 레시피 입력 자재면 raw-store 에 생성. */

package/dist/mes-kernel.js

@@ -58,8 +58,29 @@ export class MesKernel extends FlowEngine {
         super(tenantId, policy);
         this.mesSpec = mesSpec;
         /* 정의가 있으면 그 안의 오퍼레이션 명세(소요·변동·모수)를 커널이 소비한다 — 없으면 기본값 경로. */
-        if (mesSpec?.definition?.operations)
+        if (mesSpec?.definition?.operations) {
             this.loadOperations(mesSpec.definition.operations);
+            this.assertNoDoubleProduction(mesSpec.definition.operations);
+        }
+    }
+    /**
+     * **산출을 두 곳에서 만들지 않는다** — 기동 때 막는다.
+     *
+     * MES 는 레시피로 산출을 만든다: WIP 사슬(스텝마다 앞의 WIP 을 먹고 다음 WIP 을 낸다) · **직렬번호**
+     * (회사 프리픽스 + 일련번호) · **수율**(양품/불량이 처분을 가른다) · 생산오더 연결. 코어의 일반
+     * 자재 명세(`use: 'produced'`)는 **비직렬 클래스+수량**이라 그 넷을 표현하지 못한다.
+     *
+     * 그래서 MES 를 일반 선언으로 옮기지 않는다 — 옮기면 정체성·수율·오더 연결을 **잃는다**(§4-20).
+     * 대신 둘이 겹치면 **같은 산출을 두 번 만들게** 되므로, 그 조합을 기동 시점에 거부한다.
+     * 런타임에 조용히 두 배가 되는 것보다 기동이 실패하는 편이 낫다(재고가 거짓이 되면 그 위의
+     * 모든 계산이 거짓이 된다).
+     */
+    assertNoDoubleProduction(ops) {
+        const bad = ops.filter(o => (o.materialSpecification ?? []).some(m => m.use === 'produced')).map(o => o.key);
+        if (!bad.length)
+            return;
+        throw new Error(`MES recipe already produces outputs — operations [${bad.join(', ')}] must not also declare materialSpecification use:'produced' ` +
+            '(that would create the same output twice). Consumption specs are fine; declare production in the recipe.');
     }
     productOf(gtin) { return PRODUCTS.find(p => p.gtin === gtin); }
     /**
@@ -110,7 +131,7 @@ export class MesKernel extends FlowEngine {
         const product = PRODUCTS[this.orderSeq % PRODUCTS.length];
         const id = `order-${++this.orderSeq}`;
         const wo = gdtiUri(CP, '403', ++this.soSeq);
-        const order = { id, kind: 'workorder', status: 'created', gtin: product.gtin, requested: 1, fulfilled: 0, bizTransaction: wo, allocated: [], picked: [] };
+        const order = { id, kind: 'workorder', status: 'created', gtin: product.gtin, requested: 1, fulfilled: 0, bizTransaction: wo, allocated: [], picked: [], ...this.promiseOf(_spec) };
         this.orders.set(id, order);
         this.emitOrder(order);
     }
@@ -150,11 +171,27 @@ export class MesKernel extends FlowEngine {
         this.emitTask(task);
     }
     /** op 완료 = 변환. 라우트 인덱스로 분기: 첫=BOM 소비→WIP, 중간=WIP→WIP, 마지막(조립)=WIP→완성차(수율→OEE 품질). */
+    /**
+     * MES 는 완료 시점에 **오더와 제품 정의**를 딛고 선다 — 둘 중 하나만 없어도 끝맺을 수 없다.
+     *
+     * 씨앗이 이미 이행된 오더를 심지 않으므로(남은 수량 0) 그 오더에 딸린 작업만 남을 수 있고,
+     * 관측이 오더 연결을 담지 못한 작업도 있다. 그때 예전에는 `order.gtin` 에서 던졌고 **그 예외
+     * 하나가 정확도 추세 전체를 죽였다.** 이제 코어가 이 답을 보고 그 작업만 접는다.
+     */
+    canComplete(t) {
+        if (this.mesSpec)
+            return !!(t.orderId && this.orders.get(t.orderId));
+        const order = t.orderId ? this.orders.get(t.orderId) : undefined;
+        return !!order && !!this.productOf(order.gtin);
+    }
     onTaskComplete(t) {
         if (this.mesSpec)
             return this.onTaskCompleteDef(t);
+        /* 여기 도달했다면 `canComplete` 가 이미 확인했다 — 그래도 단정(`!`)은 쓰지 않는다. */
         const order = this.orders.get(t.orderId);
-        const product = this.productOf(order.gtin);
+        const product = order && this.productOf(order.gtin);
+        if (!order || !product)
+            throw new Error(`task ${t.id}: order/product vanished between the core check and the domain hook`);
         const i = ROUTE.findIndex(s => s.kind === t.kind);
         const loc = this.locations.get(t.toNode);
         const isLast = i === ROUTE.length - 1;
@@ -196,6 +233,18 @@ export class MesKernel extends FlowEngine {
     serialOf(materialKey, serial) {
         return sgtinUri(this.mesSpec.companyPrefix, this.mesSpec.binding[materialKey], serial);
     }
+    /**
+     * 라우트를 용량 계산에 알려 준다 — 수율을 거슬러 올릴 때 순서가 곧 계산이다.
+     *
+     * 순서를 모르면 선언 순서대로 세는데, 그러면 하류에서 잃는 몫이 엉뚱한 공정에 얹힌다(조용히
+     * 틀린다). 생산 정의를 가진 커널만 이 답을 안다.
+     */
+    routeKeys() {
+        if (!this.mesSpec)
+            return undefined;
+        const d = this.mesSpec.definition;
+        return d.routes?.find(r => r.key === this.recipeDef().route)?.steps;
+    }
     /** recipe.route → 오퍼레이션 시퀀스 해소. */
     routeOps() {
         const d = this.mesSpec.definition;
@@ -208,6 +257,9 @@ export class MesKernel extends FlowEngine {
         if (!rawStore)
             return;
         const gtin = this.pickGtin(spec.content.skuMix);
+        /* 품목 구성이 비어 있으면 도착을 만들지 않는다 — 무엇이 왔는지 말할 수 없는 입고는 사실이 아니다. */
+        if (!gtin)
+            return;
         const inputKey = this.recipeDef().inputs.map(i => i.material).find(k => this.classOf(k) === gtin);
         if (!inputKey)
             return;
@@ -221,7 +273,7 @@ export class MesKernel extends FlowEngine {
         const rc = this.recipeDef();
         const id = `order-${++this.orderSeq}`;
         const wo = gdtiUri(this.mesSpec.companyPrefix, '403', ++this.soSeq);
-        const order = { id, kind: 'workorder', status: 'created', gtin: this.classOf(rc.outputs[0].material), requested: 1, fulfilled: 0, bizTransaction: wo, allocated: [], picked: [] };
+        const order = { id, kind: 'workorder', status: 'created', gtin: this.classOf(rc.outputs[0].material), requested: 1, fulfilled: 0, bizTransaction: wo, allocated: [], picked: [], ...this.promiseOf(_spec) };
         this.orders.set(id, order);
         this.emitOrder(order);
     }
@@ -259,6 +311,8 @@ export class MesKernel extends FlowEngine {
     /** 정의 모드 완료 — 라우트 인덱스: 중간=WIP 변환+다음 스텝, 마지막=완제품(수율). */
     onTaskCompleteDef(t) {
         const order = this.orders.get(t.orderId);
+        if (!order)
+            throw new Error(`task ${t.id}: order vanished between the core check and the domain hook`);
         const rc = this.recipeDef();
         const ops = this.routeOps();
         const i = ops.findIndex(s => s.key === t.kind);

package/dist/observed-reducer.d.ts

@@ -53,7 +53,41 @@ export declare class ObservedReducer {
     revision: number;
     /** 받은 정정 선언 — 상태에 반영하지 않되 **버리지도 않는다**(소비처가 볼 수 있게). */
     private corrections;
+    /**
+     * 자원별 **교대 선언** — 미러가 "지금 근무 중인가" 를 스스로 판정하기 위한 재료.
+     *
+     * 상태(`EquipmentState`)에 넣지 않는다: 시뮬 스냅샷도 이것을 내보내지 않으므로 넣으면 두 구동이
+     * 갈라진다(적합성 하네스가 `mirrorOnly` 로 잡는다). 이것은 **판정의 입력**이고, 나가는 것은 판정뿐이다.
+     */
+    private shifts;
+    /** 시각 해석 기준(보드 선언) — 없으면 UTC. 캘린더의 `HH:MM` 이 어느 기준인지 정한다. */
+    private utcOffsetMinutes?;
     constructor(board: BoardDef);
+    /**
+     * **구조를 갈아탄다** — 관측된 사실은 지키고 토폴로지만 새 선언으로 바꾼다.
+     *
+     * 공장은 바뀐다. 도장 부스를 넷 더 놓고, 라인을 하나 접는다. 그런데 지금까지는 구조가 바뀌면
+     * **그 트윈의 저널을 통째로 지우는 것**이 유일한 길이었다 — 안 지우면 옛 이벤트를 새 공장에 대고
+     * 접게 되어 이력이 거짓말을 한다. 역사를 잃거나 거짓말을 하거나, 둘뿐이었다.
+     *
+     * 셋째 길이 이것이다: 이벤트가 **자기 구조를 달고** 다니고, 재생은 구조가 바뀌는 지점에서 여기를
+     * 불러 갈아탄 뒤 이어 접는다. 그러면 "그때 그 공장의 사실" 로 계속 읽힌다.
+     *
+     * ── 무엇을 지키고 무엇을 버리는가 ───────────────────────────────────────
+     * **관측은 지킨다** — 물품·오더·작업·집합은 구조와 무관한 사실이다(팔레트는 부스를 늘려도 그대로다).
+     * **사라진 자원은 버린다** — 없어진 설비의 상태를 계속 들고 있으면 화면이 없는 설비를 그린다.
+     * 다만 **몇 개를 버렸는지 돌려준다.** 조용히 사라지면 사용자는 수가 줄어든 것을 눈치채지 못한다.
+     *
+     * 관측으로 알게 된 자리(`origin: 'observed'`)는 **새 마스터에 없어도 남긴다** — 마스터가 모르는
+     * 자리에서 물건이 실제로 보였다는 사실은 구조를 바꾼다고 사라지지 않는다.
+     */
+    adoptStructure(board: BoardDef): {
+        locationsAdded: number;
+        locationsDropped: number;
+        equipmentDropped: number;
+        personsDropped: number;
+        assetsDropped: number;
+    };
     /** 마스터 동기 — 로케이션 추가/변경/제거. */
     applyMaster(u: MasterUpdate): void;
     /**
@@ -81,6 +115,14 @@ export declare class ObservedReducer {
     private stale;
     /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
     private lastAt;
+    /**
+     * **미러의 "지금"** — 지금까지 들은 것 중 가장 늦은 발생 시각.
+     *
+     * 미러는 스스로 시간을 굴리지 않지만, 시각으로만 일어나는 사실(유효 기간 만료)을 판정하려면 기준이
+     * 필요하다. 미러의 정직한 기준은 **"내가 마지막으로 들은 시점"** 이다. 아무것도 못 들었으면
+     * 판정하지 않는다(모르면 단정하지 않는다).
+     */
+    private observedAtMs?;
     /** 이벤트 1건 반영 — eventType 으로 EPCIS vs 운영 델타 분기. */
     apply(e: CanonicalEnvelope): void;
     private applyEpcis;
@@ -99,5 +141,24 @@ export declare class ObservedReducer {
     /** 이탈(DELETE) — 아이템 + 조립 자식(재귀) 제거. 화물 SSCC DELETE 시 팔레트도 함께 이탈. */
     private remove;
     /** 현재 투영 State — 자리 점유는 아이템 위치 집계로 유도(pure projection). */
+    /**
+     * 마지막으로 들은 발생 시각(ms) — **관측 구동의 "지금".**
+     *
+     * 시각으로만 바뀌는 사실(납기 초과·유효 기간·교대)을 판정하려면 기준이 필요하고, 관측 모드에는
+     * 굴러가는 시계가 없다. 정직한 기준은 "내가 마지막으로 들은 시점" 이다. 아무것도 못 들었으면
+     * `undefined` — 없는 기준으로 단정하지 않는다.
+     */
+    get lastObservedMs(): number | undefined;
+    /** 선언된 교대만 기억한다 — 아무 선언이 없으면 키를 만들지 않는다(24시간 가용이 기존 거동). */
+    private rememberShift;
+    /**
+     * 지금 근무 시간 밖인가 — 시뮬과 **같은 함수**(`offCalendarAt`)를 미러의 시각으로 부른다.
+     *
+     * 판정을 델타로 받지 않는 이유는 유효 기간과 같다: 교대 경계는 **이벤트 없이 시각만으로** 넘어가므로,
+     * 유휴 상태로 경계를 지난 자원은 실어 보낸 옛 판정에 머문다. 아무것도 못 들었으면 판정하지 않는다.
+     */
+    private offShiftPart;
+    /** 유효 기간 밖이면 그 이유를 붙인다 — 미러의 시각 기준은 `observedAtMs`(마지막으로 들은 시점). */
+    private effectivityPart;
     snapshot(): ProjectedState;
 }