@operato/twin-kernel 0.6.1 → 0.6.3

package/dist/contract.d.ts

@@ -806,6 +806,14 @@ export interface AssetState extends EffectivePeriod {
      */
     effectivity?: Effectivity;
 }
+/**
+ * 작업 하나의 관측 상태 — **ISA-95 `SegmentResponse`**(Part 4, 실적).
+ *
+ * 1차 출처(B2MML v0701): `SegmentResponseType`(B2MML-OperationsPerformance.xsd) — 실적 하나에 응답이
+ * 여럿 들리고, 응답마다 어느 공정 구간을 언제 누구·무엇으로 했는지가 실린다(`PersonnelActual` ·
+ * `EquipmentActual` · `MaterialActual`). 이 계약의 `personnel`·`resourceRef`·`materialActual` 이 그
+ * 자리들이다.
+ */
 export interface TaskState {
     id: string;
     kind: string;
@@ -856,6 +864,16 @@ export interface TaskState {
         uom?: string;
     }[];
 }
+/**
+ * 오더 하나의 관측 상태 — **ISA-95 `OperationsRequest`**(Part 4, 일정).
+ *
+ * 1차 출처(B2MML v0701): `OperationsRequestType`(B2MML-OperationsSchedule.xsd) — 일정 하나에 요구가
+ * 여럿 들리고, 요구는 `SegmentRequirement` 로 쪼개진다. 여기 담는 것은 **원본이 낸 요구를 트윈이
+ * 관측한 것**이라 계획 자체가 아니다(그 구분이 ADR-0030 의 이유다).
+ *
+ * 실적 쪽 대응은 `TaskState`(`SegmentResponse`) 다 — 요구와 응답을 한 짝으로 읽어야 "얼마나 시켰고
+ * 얼마나 됐나" 가 나온다.
+ */
 export interface OrderState {
     id: string;
     kind: string;
@@ -874,6 +892,22 @@ export interface OrderState {
     requested?: number;
     fulfilled?: number;
     lines?: ObservedOrderLine[];
+    /**
+     * 이 오더가 **확보해 둔 물품들** — 진행 중인 할당.
+     *
+     * 이것이 상태에 없으면 **웜스타트가 잃는다.** 잃으면 되살아난 오더는 아무것도 안 잡은 것처럼
+     * 보이고, 그 오더에 딸린 진행 중 작업이 완료될 때 계보(`TransformationEvent`)가 **입력 없이**
+     * 나간다 — "무엇이 무엇으로 바뀌었나" 의 절반이 사라진다. 실제로 그렇게 되고 있었다.
+     *
+     * 씨앗이 잃은 것은 예측도 모른다 — 진행 중 자재를 안 잡은 것으로 놓고 미래를 굴리면 답이
+     * 낙관 쪽으로 치우친다(`hydrateObserved` 가 상태를 지키는 이유와 같다).
+     */
+    allocated?: string[];
+    /**
+     * 이 오더의 거래번호(작업지시·PO·SO) — 계보와 EPCIS 이벤트가 **무슨 거래로** 일어났는지 잇는 축.
+     * 이것도 상태에 없어서 되살아난 오더는 빈 문자열을 갖고, 이후 모든 이벤트의 거래번호가 빈다.
+     */
+    bizTransaction?: string;
     /** 우선순위 — 표준 `OperationsRequest.Priority`. 작은 값이 급하다. 오더 할당 순서를 정한다. */
     priority?: number;
     /** 예정 착수 — 표준 `OperationsRequest.StartTime`. */
@@ -1230,6 +1264,15 @@ export interface OrderStatusDelta {
     priority?: number;
     startTime?: ISOTime;
     endTime?: ISOTime;
+    /**
+     * 이 오더가 **확보해 둔 물품들**과 그 **거래번호** — 진행 중인 할당.
+     *
+     * 델타가 나르지 않으면 웜스타트가 잃는다. 잃으면 되살아난 오더는 아무것도 안 잡은 것처럼
+     * 보이고, 그 오더의 진행 중 작업이 완료될 때 계보(`TransformationEvent`)가 **입력 없이** 나간다 —
+     * "무엇이 무엇으로 바뀌었나" 의 절반이 사라진다. 실제로 그렇게 되고 있었다.
+     */
+    allocated?: string[];
+    bizTransaction?: string;
 }
 export declare const CMD: {
     readonly orderHold: "order.hold";

package/dist/domain-catalog.d.ts

@@ -34,15 +34,40 @@ export interface TwinAxisInfo {
      * (저장·계약의 이름과 갈라지면 그 순간 방언이 생긴다).
      */
     axis: string;
+    /**
+     * 이 축을 **어디서 읽나.**
+     *
+     * 없으면 `'document'` — 지금까지의 모든 축이 그렇다(선언이고, 인제스트가 쓴다). 그런데 표준이
+     * 요구하는 것 중에는 **선언이 아닌 것**이 있다: 작업 일정과 실적은 사람이 적어 두는 값이 아니라
+     * 현장이 낳는 사실이고, 그 집은 커널 상태와 저널이다(ISA-95 Part 4).
+     *
+     * 이 칸이 없으면 축만 늘려도 소비처가 board 에서 찾다가 **언제나 0 을 답한다** — 오류 없이,
+     * 그냥 빈 공장처럼. 이 프로젝트가 이미 그 모양으로 한 번 무너졌다(옛 어휘 보드가 자리 0·설비 0).
+     *
+     *  · `document` — 저장된 트윈 모델 안. `path` 가 그 자리를 말한다
+     *  · `state`    — 커널 상태. **지금의 사실**이고 커널이 돌 때만 있다(멈추면 `null`, 0 이 아니다)
+     *  · `journal`  — 저널. 과거까지 있고 커널이 멈춰도 남는다
+     */
+    source?: 'document' | 'state' | 'journal';
+    /**
+     * 이 축이 **시간축을 갖나** — 과거 시점으로 되짚을 수 있는가(저널 폴드).
+     *
+     * 선언은 시간축이 없다(그 시점의 선언은 구조 리비전이 답한다). 관측은 있다 — 그래서 이 표시가
+     * 필요하다: 화면이 시각 커서를 이 축에 걸어도 되는지 알아야 한다.
+     */
+    historical?: boolean;
     /**
      * board 안에서의 자리. 최상위면 `axis` 와 같고, 중첩이면 경로다
      * (`productionSpec.definition.recipes`).
      *
+     * **`source: 'document'` 일 때만 있다.** 상태·저널 축에는 board 안의 자리가 없다 — 빈 문자열로
+     * 두면 소비처가 board 루트를 읽고 통째로 잘못된 답을 만든다.
+     *
      * **레시피·라우트는 저장상 `productionSpec` 안에 있지만 개념으로는 1급**이다 — 사람은
      * "레시피" 를 찾지 "생산 정의 안의 레시피" 를 찾지 않는다. 저장 위치가 개념을 가두면
      * 화면이 저장 구조를 흉내 내게 되고, 그건 `ADR-0032`(board 는 캐시) 뒤에 무의미해진다.
      */
-    path: string;
+    path?: string;
     /** i18n 키 — 사람 언어는 표현 계층이 렌더한다(L2). */
     label: string;
     /** 표준 온톨로지 투영. 표준에 자리가 없으면 **빈 객체**(숨기지 않는다). */
@@ -147,6 +172,21 @@ export interface TwinPropertyInfo {
 export declare const TWIN_PROPERTIES: TwinPropertyInfo[];
 /** 이 축이 보여 줄 속성들 — 없으면 빈 배열(속성 없는 축이 정상이다). */
 export declare const propertiesOf: (axis: string) => TwinPropertyInfo[];
+/**
+ * 이 축은 **선언에서 읽나** — `source` 를 말하지 않은 축은 문서 축이다(기존 14축).
+ *
+ * 소비처가 `source` 를 직접 비교하면 기본값 규칙이 자리마다 복사되고, 한 곳이 빠지면 그 축은
+ * board 루트를 읽어 조용히 잘못된 답을 낸다. 판정은 여기 하나다.
+ */
+export declare const axisSource: (axis: string) => "document" | "state" | "journal";
+/**
+ * 문서에서 이 축을 찾을 자리 — **문서 축이 아니면 던진다.**
+ *
+ * 상태·저널 축에는 board 안의 자리가 없다. 그런데 옛 소비처는 `info.path` 를 무조건 읽었으므로,
+ * 그 자리가 `undefined` 면 board 루트를 읽고 **오류 없이 0 을 답한다**(이 프로젝트가 겪은 실패 모양).
+ * 그래서 조용히 넘기지 않고 부르는 쪽을 멈춘다.
+ */
+export declare function documentPath(axis: string): string;
 /** 이 축에서 나가는 관계 · 이 축으로 들어오는 관계 — 항목 패널의 "이어진 것" 양방향. */
 export declare const relationsFrom: (axis: string) => TwinRelationInfo[];
 export declare const relationsTo: (axis: string) => TwinRelationInfo[];

package/dist/domain-catalog.js

@@ -43,7 +43,28 @@ export const TWIN_AXES = [
     { axis: 'routes', path: 'productionSpec.definition.routes', label: 'twin.axis.routes', kind: 'spec',
         standardClass: { isa95: 'OperationsSegment' } },
     { axis: 'materials', path: 'productionSpec.definition.materials', label: 'twin.axis.materials', kind: 'class',
-        standardClass: { isa95: 'MaterialDefinition' } }
+        standardClass: { isa95: 'MaterialDefinition' } },
+    /*
+     * ── ISA-95 Part 4 — 일정과 실적 ────────────────────────────────────────────────
+     *
+     * 여기부터는 **선언이 아니다.** 오더와 작업은 사람이 board 에 적어 두는 값이 아니라 현장이 낳는
+     * 사실이고, 그 집은 커널 상태와 저널이다. 그래서 `source` 가 `'state'` 이고 `path` 가 없다.
+     *
+     * ── 왜 축이어야 하나 ──────────────────────────────────────────────────────────
+     * 이 둘이 축이 아니던 동안 "이 트윈이 표준의 어디를 채우나" 라는 질문은 **절반만** 답했다. Part 2
+     * 자원 모델은 여덟이 완전한데 Part 4 는 통째로 비어 있었다 — 런타임에는 실재하는데 조회 모델에는
+     * 없었기 때문이다. 실적을 성과 화면이 답한다는 것은 사실이지만, 그건 **집계**이고 개념 자체를
+     * 가리켜 걸어 들어갈 자리는 없었다(어느 오더가 어느 공정에서 무엇을 먹었나).
+     *
+     * ── 왜 테이블로 투영하지 않나 ─────────────────────────────────────────────────
+     * 정본이 저널이다. 구조 엔티티는 **원본이 낼 수 있는 것만** 담고(ADR-0032-D), 오더는 원본이 낸
+     * 것이지만 트윈이 **관측한** 것이다. 투영은 규모에서 성능이 필요해질 때 KPI 폴드와 같은 급의
+     * 별도 결정으로 한다.
+     */
+    { axis: 'orders', label: 'twin.axis.orders', kind: 'instance', source: 'state', historical: true,
+        standardClass: { isa95: 'OperationsRequest', epcis: 'TransactionEvent' } },
+    { axis: 'tasks', label: 'twin.axis.tasks', kind: 'instance', source: 'state', historical: true,
+        standardClass: { isa95: 'SegmentResponse', epcis: 'TransformationEvent' } }
 ];
 /** 관계 전체 — 지도의 선과 항목의 이웃이 여기서 나온다(화면은 이 목록을 갖지 않는다). */
 export const TWIN_RELATIONS = [
@@ -63,6 +84,23 @@ export const TWIN_RELATIONS = [
     { from: 'recipes', field: 'inputs[].material', target: { kind: 'axis', axis: 'materials' }, via: 'twin.rel.input' },
     { from: 'recipes', field: 'outputs[].material', target: { kind: 'axis', axis: 'materials' }, via: 'twin.rel.output' },
     { from: 'routes', field: 'steps[]', target: { kind: 'axis', axis: 'operations' }, via: 'twin.rel.step' },
+    /*
+     * 일정·실적의 관계 — **관측 관계다.** 선언 관계는 "그렇게 만들기로 했다" 이고, 이것은 "그렇게
+     * 일어났다" 다. 관계가 없으면 이 두 축은 지도에서 떠 있는 카드가 된다(그러면 걸어 들어갈 수 없다).
+     */
+    /*
+     * 오더가 무엇을 만드나 — **자재 키가 아니라 GS1 품목 참조다**(`lines[].gtin`). 자재와 이어 주는
+     * 것은 `productionSpec.binding` 이고 그 해소는 호스트가 한다 — 자리·구역과 같은 `external` 이다.
+     * 축을 직접 가리키게 적으면 없는 필드를 가리키는 선언이 된다(계약을 보고 고쳤다).
+     */
+    { from: 'orders', field: 'lines[].gtin', target: { kind: 'external', entity: 'gs1.itemRef' }, via: 'twin.rel.item', optional: true },
+    { from: 'tasks', field: 'orderId', target: { kind: 'axis', axis: 'orders' }, via: 'twin.rel.order', optional: true },
+    /* 작업의 `kind` 는 그 공정의 키다(라우트의 단계 이름 그대로 — `mes-kernel` 의 공정 목록이 그 증거). */
+    { from: 'tasks', field: 'kind', target: { kind: 'axis', axis: 'operations' }, via: 'twin.rel.operation', optional: true },
+    { from: 'tasks', field: 'fromNode', target: { kind: 'axis', axis: 'locations' }, via: 'twin.rel.from', optional: true },
+    { from: 'tasks', field: 'toNode', target: { kind: 'axis', axis: 'locations' }, via: 'twin.rel.at', optional: true },
+    { from: 'tasks', field: 'resourceRef', target: { kind: 'axis', axis: 'equipment' }, via: 'twin.rel.by', optional: true },
+    { from: 'tasks', field: 'personnel[]', target: { kind: 'axis', axis: 'persons' }, via: 'twin.rel.crew', optional: true },
     /* 공정이 도는 자리·자원 — 항목이 아니라 **타입**을 가리킨다 */
     { from: 'operations', field: 'locationType', target: { kind: 'type', role: 'location' }, via: 'twin.rel.at', optional: true },
     { from: 'operations', field: 'resourceType', target: { kind: 'type', role: 'equipment' }, via: 'twin.rel.by', optional: true }
@@ -89,6 +127,28 @@ export const TWIN_PROPERTIES = [
 ];
 /** 이 축이 보여 줄 속성들 — 없으면 빈 배열(속성 없는 축이 정상이다). */
 export const propertiesOf = (axis) => TWIN_PROPERTIES.filter(p => p.axis === axis);
+/**
+ * 이 축은 **선언에서 읽나** — `source` 를 말하지 않은 축은 문서 축이다(기존 14축).
+ *
+ * 소비처가 `source` 를 직접 비교하면 기본값 규칙이 자리마다 복사되고, 한 곳이 빠지면 그 축은
+ * board 루트를 읽어 조용히 잘못된 답을 낸다. 판정은 여기 하나다.
+ */
+export const axisSource = (axis) => TWIN_AXES.find(a => a.axis === axis)?.source ?? 'document';
+/**
+ * 문서에서 이 축을 찾을 자리 — **문서 축이 아니면 던진다.**
+ *
+ * 상태·저널 축에는 board 안의 자리가 없다. 그런데 옛 소비처는 `info.path` 를 무조건 읽었으므로,
+ * 그 자리가 `undefined` 면 board 루트를 읽고 **오류 없이 0 을 답한다**(이 프로젝트가 겪은 실패 모양).
+ * 그래서 조용히 넘기지 않고 부르는 쪽을 멈춘다.
+ */
+export function documentPath(axis) {
+    const info = TWIN_AXES.find(a => a.axis === axis);
+    if (!info)
+        throw new Error(`unknown twin axis: "${axis}"`);
+    if (axisSource(axis) !== 'document' || !info.path)
+        throw new Error(`axis "${axis}" is not read from the document (source: ${axisSource(axis)}) — read it from the ${axisSource(axis)}`);
+    return info.path;
+}
 /** 이 축에서 나가는 관계 · 이 축으로 들어오는 관계 — 항목 패널의 "이어진 것" 양방향. */
 export const relationsFrom = (axis) => TWIN_RELATIONS.filter(r => r.from === axis);
 export const relationsTo = (axis) => TWIN_RELATIONS.filter(r => r.target.kind === 'axis' && r.target.axis === axis);

package/dist/flow-engine.js

@@ -520,7 +520,11 @@ export class FlowEngine {
                    없다.** 라이브 트윈이 납기 초과를 한 번도 보고하지 못한 원인 중 하나였다. */
                 ...(o.endTime ? { endTime: o.endTime } : {}),
                 ...(o.startTime ? { startTime: o.startTime } : {}),
-                ...(o.priority !== undefined ? { priority: o.priority } : {})
+                ...(o.priority !== undefined ? { priority: o.priority } : {}),
+                /* 확보분과 거래번호도 함께 옮긴다 — 여기서 떨구면 위에서 실어 온 것이 마지막 한 걸음에서
+                   사라진다(같은 사실이 델타·스냅샷·이 변환 **세 길**을 지난다). */
+                ...(o.allocated?.length ? { allocated: o.allocated } : {}),
+                ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {})
             }));
         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);
@@ -534,7 +538,10 @@ export class FlowEngine {
                 continue; // 이미 이행 완료 → 예측 대상 아님
             this.orders.set(o.orderId, {
                 id: o.orderId, kind: o.kind, status: 'created', requested: remaining, fulfilled: 0,
-                bizTransaction: '', allocated: [], picked: [], shipmentEpc: null, lines,
+                /* **확보해 둔 것과 거래번호를 이어받는다.** 비우면 되살아난 오더가 아무것도 안 잡은 것처럼
+                   보이고, 그 오더의 진행 중 작업이 완료될 때 계보가 입력 없이 나간다. 상태가 말해 주지
+                   않으면(옛 저널) 그때는 비는 것이 사실이다 — 없는 것을 지어내지 않는다. */
+                bizTransaction: o.bizTransaction ?? '', allocated: (o.allocated ?? []).slice(), picked: [], shipmentEpc: null, lines,
                 /* **보류를 이어받는다** — 잃으면 씨앗이 사람이 일부러 멈춘 오더를 다시 계획해 내보낸다.
                    씨앗 왕복 대조가 이것을 잡았다(그 전에는 사람이 코드를 읽어야만 알 수 있었다). */
                 ...(o.held ? { held: true } : {}),
@@ -860,6 +867,10 @@ export class FlowEngine {
                 ...(o.priority !== undefined ? { priority: o.priority } : {}),
                 ...(o.startTime ? { startTime: o.startTime } : {}),
                 ...(o.endTime ? { endTime: o.endTime } : {}),
+                /* 진행 중 확보분과 거래번호 — **스냅샷에도** 실어야 한다. 델타에만 실으면 스냅샷으로
+                   재기동하는 경로(체크포인트)에서 그대로 잃는다(같은 사실을 두 길로 나르는 값이다). */
+                ...(o.allocated?.length ? { allocated: o.allocated.slice() } : {}),
+                ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}),
                 held: o.held
             })),
             attentions: this.computeAttentions(),
@@ -1460,7 +1471,11 @@ export class FlowEngine {
             ...(o.priority !== undefined ? { priority: o.priority } : {}),
             ...(o.startTime ? { startTime: o.startTime } : {}),
             ...(o.endTime ? { endTime: o.endTime } : {}),
-            ...(o.lines?.length ? { lines: o.lines.map(l => ({ gtin: l.gtin, requested: l.requested })) } : {})
+            ...(o.lines?.length ? { lines: o.lines.map(l => ({ gtin: l.gtin, requested: l.requested })) } : {}),
+            /* 진행 중 할당과 거래번호를 함께 싣는다 — 이것이 없으면 웜스타트가 잃고, 되살아난 오더의
+               계보가 입력 없이 나간다(무엇이 무엇으로 바뀌었나의 절반이 사라진다). */
+            ...(o.allocated?.length ? { allocated: o.allocated.slice() } : {}),
+            ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {})
         });
     }
     // ── 내부 mechanics ─────────────────────────────────────────────────────────

package/dist/observed-reducer.js

@@ -342,6 +342,10 @@ export class ObservedReducer {
                     ...(d.priority !== undefined ? { priority: d.priority } : {}),
                     ...(d.startTime ? { startTime: d.startTime } : {}),
                     ...(d.endTime ? { endTime: d.endTime } : {}),
+                    /* 진행 중 확보분과 거래번호 — **미러도 같은 필드를 채운다.** 시뮬만 아는 사실을 두면
+                       그 위에서 세운 예측이 두 구동에서 달라진다(패리티 검사가 지키는 것이 이것이다). */
+                    ...(d.allocated?.length ? { allocated: d.allocated.slice() } : {}),
+                    ...(d.bizTransaction ? { bizTransaction: d.bizTransaction } : {}),
                     held: d.held
                 });
                 break;

package/dist-cjs/index.cjs

@@ -71,6 +71,7 @@ __export(index_exports, {
   aggregationEvent: () => aggregationEvent,
   analyzeCapacity: () => analyzeCapacity,
   axisInfo: () => axisInfo,
+  axisSource: () => axisSource,
   capabilitiesForType: () => capabilitiesForType,
   classClosure: () => classClosure,
   compareStates: () => compareStates,
@@ -79,6 +80,7 @@ __export(index_exports, {
   conversionFactorOf: () => conversionFactorOf,
   counterfactualAt: () => counterfactualAt,
   deriveAttentions: () => deriveAttentions,
+  documentPath: () => documentPath,
   dueStatusOf: () => dueStatusOf,
   effectivityAt: () => effectivityAt,
   fefoPolicy: () => fefoPolicy,
@@ -1181,6 +1183,10 @@ var ObservedReducer = class {
           ...d.priority !== void 0 ? { priority: d.priority } : {},
           ...d.startTime ? { startTime: d.startTime } : {},
           ...d.endTime ? { endTime: d.endTime } : {},
+          /* 진행 중 확보분과 거래번호 — **미러도 같은 필드를 채운다.** 시뮬만 아는 사실을 두면
+             그 위에서 세운 예측이 두 구동에서 달라진다(패리티 검사가 지키는 것이 이것이다). */
+          ...d.allocated?.length ? { allocated: d.allocated.slice() } : {},
+          ...d.bizTransaction ? { bizTransaction: d.bizTransaction } : {},
           held: d.held
         });
         break;
@@ -1668,6 +1674,39 @@ var TWIN_AXES = [
     label: "twin.axis.materials",
     kind: "class",
     standardClass: { isa95: "MaterialDefinition" }
+  },
+  /*
+   * ── ISA-95 Part 4 — 일정과 실적 ────────────────────────────────────────────────
+   *
+   * 여기부터는 **선언이 아니다.** 오더와 작업은 사람이 board 에 적어 두는 값이 아니라 현장이 낳는
+   * 사실이고, 그 집은 커널 상태와 저널이다. 그래서 `source` 가 `'state'` 이고 `path` 가 없다.
+   *
+   * ── 왜 축이어야 하나 ──────────────────────────────────────────────────────────
+   * 이 둘이 축이 아니던 동안 "이 트윈이 표준의 어디를 채우나" 라는 질문은 **절반만** 답했다. Part 2
+   * 자원 모델은 여덟이 완전한데 Part 4 는 통째로 비어 있었다 — 런타임에는 실재하는데 조회 모델에는
+   * 없었기 때문이다. 실적을 성과 화면이 답한다는 것은 사실이지만, 그건 **집계**이고 개념 자체를
+   * 가리켜 걸어 들어갈 자리는 없었다(어느 오더가 어느 공정에서 무엇을 먹었나).
+   *
+   * ── 왜 테이블로 투영하지 않나 ─────────────────────────────────────────────────
+   * 정본이 저널이다. 구조 엔티티는 **원본이 낼 수 있는 것만** 담고(ADR-0032-D), 오더는 원본이 낸
+   * 것이지만 트윈이 **관측한** 것이다. 투영은 규모에서 성능이 필요해질 때 KPI 폴드와 같은 급의
+   * 별도 결정으로 한다.
+   */
+  {
+    axis: "orders",
+    label: "twin.axis.orders",
+    kind: "instance",
+    source: "state",
+    historical: true,
+    standardClass: { isa95: "OperationsRequest", epcis: "TransactionEvent" }
+  },
+  {
+    axis: "tasks",
+    label: "twin.axis.tasks",
+    kind: "instance",
+    source: "state",
+    historical: true,
+    standardClass: { isa95: "SegmentResponse", epcis: "TransformationEvent" }
   }
 ];
 var TWIN_RELATIONS = [
@@ -1687,6 +1726,23 @@ var TWIN_RELATIONS = [
   { from: "recipes", field: "inputs[].material", target: { kind: "axis", axis: "materials" }, via: "twin.rel.input" },
   { from: "recipes", field: "outputs[].material", target: { kind: "axis", axis: "materials" }, via: "twin.rel.output" },
   { from: "routes", field: "steps[]", target: { kind: "axis", axis: "operations" }, via: "twin.rel.step" },
+  /*
+   * 일정·실적의 관계 — **관측 관계다.** 선언 관계는 "그렇게 만들기로 했다" 이고, 이것은 "그렇게
+   * 일어났다" 다. 관계가 없으면 이 두 축은 지도에서 떠 있는 카드가 된다(그러면 걸어 들어갈 수 없다).
+   */
+  /*
+   * 오더가 무엇을 만드나 — **자재 키가 아니라 GS1 품목 참조다**(`lines[].gtin`). 자재와 이어 주는
+   * 것은 `productionSpec.binding` 이고 그 해소는 호스트가 한다 — 자리·구역과 같은 `external` 이다.
+   * 축을 직접 가리키게 적으면 없는 필드를 가리키는 선언이 된다(계약을 보고 고쳤다).
+   */
+  { from: "orders", field: "lines[].gtin", target: { kind: "external", entity: "gs1.itemRef" }, via: "twin.rel.item", optional: true },
+  { from: "tasks", field: "orderId", target: { kind: "axis", axis: "orders" }, via: "twin.rel.order", optional: true },
+  /* 작업의 `kind` 는 그 공정의 키다(라우트의 단계 이름 그대로 — `mes-kernel` 의 공정 목록이 그 증거). */
+  { from: "tasks", field: "kind", target: { kind: "axis", axis: "operations" }, via: "twin.rel.operation", optional: true },
+  { from: "tasks", field: "fromNode", target: { kind: "axis", axis: "locations" }, via: "twin.rel.from", optional: true },
+  { from: "tasks", field: "toNode", target: { kind: "axis", axis: "locations" }, via: "twin.rel.at", optional: true },
+  { from: "tasks", field: "resourceRef", target: { kind: "axis", axis: "equipment" }, via: "twin.rel.by", optional: true },
+  { from: "tasks", field: "personnel[]", target: { kind: "axis", axis: "persons" }, via: "twin.rel.crew", optional: true },
   /* 공정이 도는 자리·자원 — 항목이 아니라 **타입**을 가리킨다 */
   { from: "operations", field: "locationType", target: { kind: "type", role: "location" }, via: "twin.rel.at", optional: true },
   { from: "operations", field: "resourceType", target: { kind: "type", role: "equipment" }, via: "twin.rel.by", optional: true }
@@ -1740,6 +1796,14 @@ var TWIN_PROPERTIES = [
   }
 ];
 var propertiesOf = (axis) => TWIN_PROPERTIES.filter((p) => p.axis === axis);
+var axisSource = (axis) => TWIN_AXES.find((a) => a.axis === axis)?.source ?? "document";
+function documentPath(axis) {
+  const info = TWIN_AXES.find((a) => a.axis === axis);
+  if (!info) throw new Error(`unknown twin axis: "${axis}"`);
+  if (axisSource(axis) !== "document" || !info.path)
+    throw new Error(`axis "${axis}" is not read from the document (source: ${axisSource(axis)}) \u2014 read it from the ${axisSource(axis)}`);
+  return info.path;
+}
 var relationsFrom = (axis) => TWIN_RELATIONS.filter((r) => r.from === axis);
 var relationsTo = (axis) => TWIN_RELATIONS.filter((r) => r.target.kind === "axis" && r.target.axis === axis);
 function axisInfo(axis) {
@@ -2502,7 +2566,11 @@ var FlowEngine = class {
          없다.** 라이브 트윈이 납기 초과를 한 번도 보고하지 못한 원인 중 하나였다. */
       ...o.endTime ? { endTime: o.endTime } : {},
       ...o.startTime ? { startTime: o.startTime } : {},
-      ...o.priority !== void 0 ? { priority: o.priority } : {}
+      ...o.priority !== void 0 ? { priority: o.priority } : {},
+      /* 확보분과 거래번호도 함께 옮긴다 — 여기서 떨구면 위에서 실어 온 것이 마지막 한 걸음에서
+         사라진다(같은 사실이 델타·스냅샷·이 변환 **세 길**을 지난다). */
+      ...o.allocated?.length ? { allocated: o.allocated } : {},
+      ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}
     }));
     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);
@@ -2514,8 +2582,11 @@ var FlowEngine = class {
         status: "created",
         requested: remaining,
         fulfilled: 0,
-        bizTransaction: "",
-        allocated: [],
+        /* **확보해 둔 것과 거래번호를 이어받는다.** 비우면 되살아난 오더가 아무것도 안 잡은 것처럼
+           보이고, 그 오더의 진행 중 작업이 완료될 때 계보가 입력 없이 나간다. 상태가 말해 주지
+           않으면(옛 저널) 그때는 비는 것이 사실이다 — 없는 것을 지어내지 않는다. */
+        bizTransaction: o.bizTransaction ?? "",
+        allocated: (o.allocated ?? []).slice(),
         picked: [],
         shipmentEpc: null,
         lines,
@@ -2823,6 +2894,10 @@ var FlowEngine = class {
         ...o.priority !== void 0 ? { priority: o.priority } : {},
         ...o.startTime ? { startTime: o.startTime } : {},
         ...o.endTime ? { endTime: o.endTime } : {},
+        /* 진행 중 확보분과 거래번호 — **스냅샷에도** 실어야 한다. 델타에만 실으면 스냅샷으로
+           재기동하는 경로(체크포인트)에서 그대로 잃는다(같은 사실을 두 길로 나르는 값이다). */
+        ...o.allocated?.length ? { allocated: o.allocated.slice() } : {},
+        ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {},
         held: o.held
       })),
       attentions: this.computeAttentions(),
@@ -3367,7 +3442,11 @@ var FlowEngine = class {
       ...o.priority !== void 0 ? { priority: o.priority } : {},
       ...o.startTime ? { startTime: o.startTime } : {},
       ...o.endTime ? { endTime: o.endTime } : {},
-      ...o.lines?.length ? { lines: o.lines.map((l) => ({ gtin: l.gtin, requested: l.requested })) } : {}
+      ...o.lines?.length ? { lines: o.lines.map((l) => ({ gtin: l.gtin, requested: l.requested })) } : {},
+      /* 진행 중 할당과 거래번호를 함께 싣는다 — 이것이 없으면 웜스타트가 잃고, 되살아난 오더의
+         계보가 입력 없이 나간다(무엇이 무엇으로 바뀌었나의 절반이 사라진다). */
+      ...o.allocated?.length ? { allocated: o.allocated.slice() } : {},
+      ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}
     });
   }
   // ── 내부 mechanics ─────────────────────────────────────────────────────────
@@ -4967,6 +5046,7 @@ function retiredVocabularyIn(line) {
   aggregationEvent,
   analyzeCapacity,
   axisInfo,
+  axisSource,
   capabilitiesForType,
   classClosure,
   compareStates,
@@ -4975,6 +5055,7 @@ function retiredVocabularyIn(line) {
   conversionFactorOf,
   counterfactualAt,
   deriveAttentions,
+  documentPath,
   dueStatusOf,
   effectivityAt,
   fefoPolicy,

package/package.json

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