@operato/twin-kernel 0.7.28 → 0.7.30

package/dist/flow-engine.d.ts

@@ -2,7 +2,7 @@ import type { TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, Effectiv
 import type { EpcisEvent, BizTransactionElement } from './epcis.ts';
 import type { AllocationPolicy, SlotView } from './allocation-policy.ts';
 import type { DurationEstimator, DurationContext } from './duration-estimator.ts';
-import type { OperationDef } from './domain-definition.ts';
+import type { OperationDef, IsoDuration } from './domain-definition.ts';
 import { type CapacityAnalysis } from './capacity.ts';
 import { type CommittedDemand, type OperationsCapabilityReport } from './operations-capability.ts';
 export interface FlowLocation {
@@ -237,6 +237,18 @@ export declare const ATTENTION_DEFAULTS: {
     readonly scrapPct: 15;
     readonly scrapMinSamples: 10;
 };
+/**
+ * 공정에 선언할 수 있는 것의 **어휘** — 지금은 소요시간 하나다(`declareDurations` 가 읽는다).
+ *
+ * 자리·설비의 속성처럼 「속성 id」로 부른다: 선언을 받는 문·화면·AI 가 같은 이름을 써야 하고, 그 이름이
+ * 두 곳에 적히면 한쪽만 바뀌는 순간 값이 조용히 버려진다.
+ *
+ * 이 값이 얹히는 대상은 **자리·설비가 아니라 공정 종류**다(`FlowTask.kind` = `OperationDef.key`).
+ */
+export declare const OPERATION_PROPERTY: {
+    /** 그 현장에서 이 공정이 걸리는 시간 — 실측이 없을 때 상수를 대신한다. */
+    readonly duration: "operation.duration";
+};
 /** 판정에 쓸 기준 — 대상별 선언이 있으면 그것, 없으면 기본값(그 사실을 함께 든다). */
 export interface AttentionThresholds {
     congestionPctOf?: (locationId: string) => number | undefined;
@@ -347,6 +359,13 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
      */
     protected operationSpecs: Map<string, OperationDef>;
+    /**
+     * 현장이 선언한 소요시간(작업 종류 → ms) — `declareDurations` 로 들어온다.
+     *
+     * 명세 행과 **따로** 두는 이유: 행이 없는 종류에도 시간을 줄 수 있어야 하고(창고·야드 트윈에는 행이
+     * 없다), 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다.
+     */
+    protected localDurations: Map<string, number>;
     /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
     private observer?;
     /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
@@ -673,6 +692,27 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     protected declaredOperations(): readonly OperationDef[];
     loadOperations(ops?: OperationDef[]): void;
+    /**
+     * **현장이 정한 소요시간** — 종류별로 시간만 받는다(2026-08-18).
+     *
+     * ── 왜 명세 행과 따로 받나 ──────────────────────────────────────────────────
+     * 창고·야드 트윈에는 오퍼레이션 명세 행이 **아예 없다**(실측: 35개 트윈 중 WMS·YMS 전부 0개). 그런데
+     * 그 트윈들도 `putaway`·`pick`·`spot`·`dwell` 을 돌리고, 시간은 커널 상수에서 온다 — 그 현장이 실제로
+     * 몇 분 걸리는지 말할 문이 없었다.
+     *
+     * 명세 행을 지어 만들 수는 없다: `OperationDef` 는 `label`·`intent` 를 요구하고(ISA-95
+     * `OperationsSegment`), 그 둘은 **지어내면 다른 답까지 오염시킨다**(`capacity()`·능력 보고가 의도별로
+     * 자원을 센다). 「몇 분 걸리나」를 말하려고 「무슨 종류의 작업인가」를 발명하지 않는다.
+     *
+     * ── 순서: 실측 > 현장 선언 > 원천 명세 > 상수 ──────────────────────────────
+     * 이력에서 배운 값이 가장 강하고(그 현장이 실제로 그랬다), 그다음이 **이 선언**이다 — 원천 명세보다
+     * 이긴다(원천 사본의 값이 낡았을 때 고칠 자리가 여기다). 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
+     *
+     * ── 조용히 버리지 않는다 ────────────────────────────────────────────────────
+     * 읽을 수 없는 값은 던진다. 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 도는데,
+     * 그 어긋남을 아무도 볼 수 없다(이 시스템에서 가장 비싼 종류의 침묵이다).
+     */
+    declareDurations(durations: Record<string, IsoDuration> | undefined | null): void;
     /**
      * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
      * 생산 정의를 가진 커널이 override 해서 자기 라우트를 답한다.
@@ -727,10 +767,12 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     protected committedDemands(): CommittedDemand[];
     /**
-     * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 명세(ISA-95 Duration + 변동) → ③ 도메인 상수.**
+     * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 현장 선언(`declareDurations`) →
+     * ③ 명세(ISA-95 Duration + 변동) → ④ 도메인 상수.**
      *
      * 이 순서인 이유: 실측에서 배운 값이 선언값을 이기고, 선언값이 우리가 코드에 고정한 상수를 이긴다.
-     * 셋 중 무엇을 썼는지는 `specCoverage()` 로 드러낸다 — 상수를 쓴 것이 조용히 넘어가지 않게.
+     * 선언이 둘로 갈리는 이유는 권위다 — **현장이 정한 값**이 원천이 그려 준 명세를 이긴다(ADR-0034).
+     * 무엇을 썼는지는 `specCoverage()` 로 드러낸다 — 상수를 쓴 것이 조용히 넘어가지 않게.
      * "얼마"만 소비하고 "경로"는 씬이 소유한다(좌표-free 유지).
      */
     protected durationOf(ctx: DurationContext, fallbackMs: number): number;

package/dist/flow-engine.js

@@ -67,6 +67,18 @@ export const ATTENTION_PROPERTY = {
 };
 /** 선언이 없을 때 쓰는 기본값 — **드러내 둔다**(코드 안에 숨은 상수가 아니라 계약의 일부다). */
 export const ATTENTION_DEFAULTS = { congestionPct: 90, scrapPct: 15, scrapMinSamples: 10 };
+/**
+ * 공정에 선언할 수 있는 것의 **어휘** — 지금은 소요시간 하나다(`declareDurations` 가 읽는다).
+ *
+ * 자리·설비의 속성처럼 「속성 id」로 부른다: 선언을 받는 문·화면·AI 가 같은 이름을 써야 하고, 그 이름이
+ * 두 곳에 적히면 한쪽만 바뀌는 순간 값이 조용히 버려진다.
+ *
+ * 이 값이 얹히는 대상은 **자리·설비가 아니라 공정 종류**다(`FlowTask.kind` = `OperationDef.key`).
+ */
+export const OPERATION_PROPERTY = {
+    /** 그 현장에서 이 공정이 걸리는 시간 — 실측이 없을 때 상수를 대신한다. */
+    duration: 'operation.duration'
+};
 export function deriveAttentions(view, acked, 
 /** 지금(ISO) — 납기 판정에 필요하다. **주지 않으면 지연을 판정하지 않는다**(모르면 판단하지 않는다). */
 nowIso, 
@@ -311,6 +323,13 @@ export class FlowEngine {
      * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
      */
     operationSpecs = new Map();
+    /**
+     * 현장이 선언한 소요시간(작업 종류 → ms) — `declareDurations` 로 들어온다.
+     *
+     * 명세 행과 **따로** 두는 이유: 행이 없는 종류에도 시간을 줄 수 있어야 하고(창고·야드 트윈에는 행이
+     * 없다), 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다.
+     */
+    localDurations = new Map();
     /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
     observer;
     /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
@@ -1425,6 +1444,39 @@ export class FlowEngine {
             if (o?.key)
                 this.operationSpecs.set(o.key, o);
     }
+    /**
+     * **현장이 정한 소요시간** — 종류별로 시간만 받는다(2026-08-18).
+     *
+     * ── 왜 명세 행과 따로 받나 ──────────────────────────────────────────────────
+     * 창고·야드 트윈에는 오퍼레이션 명세 행이 **아예 없다**(실측: 35개 트윈 중 WMS·YMS 전부 0개). 그런데
+     * 그 트윈들도 `putaway`·`pick`·`spot`·`dwell` 을 돌리고, 시간은 커널 상수에서 온다 — 그 현장이 실제로
+     * 몇 분 걸리는지 말할 문이 없었다.
+     *
+     * 명세 행을 지어 만들 수는 없다: `OperationDef` 는 `label`·`intent` 를 요구하고(ISA-95
+     * `OperationsSegment`), 그 둘은 **지어내면 다른 답까지 오염시킨다**(`capacity()`·능력 보고가 의도별로
+     * 자원을 센다). 「몇 분 걸리나」를 말하려고 「무슨 종류의 작업인가」를 발명하지 않는다.
+     *
+     * ── 순서: 실측 > 현장 선언 > 원천 명세 > 상수 ──────────────────────────────
+     * 이력에서 배운 값이 가장 강하고(그 현장이 실제로 그랬다), 그다음이 **이 선언**이다 — 원천 명세보다
+     * 이긴다(원천 사본의 값이 낡았을 때 고칠 자리가 여기다). 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
+     *
+     * ── 조용히 버리지 않는다 ────────────────────────────────────────────────────
+     * 읽을 수 없는 값은 던진다. 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 도는데,
+     * 그 어긋남을 아무도 볼 수 없다(이 시스템에서 가장 비싼 종류의 침묵이다).
+     */
+    declareDurations(durations) {
+        for (const [kind, text] of Object.entries(durations ?? {})) {
+            const key = String(kind ?? '').trim();
+            if (!key)
+                throw new Error('declareDurations: an operation kind is empty — say which operation the duration belongs to');
+            const ms = parseIsoDuration(text);
+            if (ms === undefined)
+                throw new Error(`declareDurations: "${text}" is not an ISO 8601 duration (operation "${key}") — the value would be dropped without a trace`);
+            if (ms <= 0)
+                throw new Error(`declareDurations: operation "${key}" cannot take ${ms}ms — a task with no duration never finishes`);
+            this.localDurations.set(key, ms);
+        }
+    }
     /**
      * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
      * 생산 정의를 가진 커널이 override 해서 자기 라우트를 답한다.
@@ -1528,10 +1580,12 @@ export class FlowEngine {
         return out;
     }
     /**
-     * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 명세(ISA-95 Duration + 변동) → ③ 도메인 상수.**
+     * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 현장 선언(`declareDurations`) →
+     * ③ 명세(ISA-95 Duration + 변동) → ④ 도메인 상수.**
      *
      * 이 순서인 이유: 실측에서 배운 값이 선언값을 이기고, 선언값이 우리가 코드에 고정한 상수를 이긴다.
-     * 셋 중 무엇을 썼는지는 `specCoverage()` 로 드러낸다 — 상수를 쓴 것이 조용히 넘어가지 않게.
+     * 선언이 둘로 갈리는 이유는 권위다 — **현장이 정한 값**이 원천이 그려 준 명세를 이긴다(ADR-0034).
+     * 무엇을 썼는지는 `specCoverage()` 로 드러낸다 — 상수를 쓴 것이 조용히 넘어가지 않게.
      * "얼마"만 소비하고 "경로"는 씬이 소유한다(좌표-free 유지).
      */
     durationOf(ctx, fallbackMs) {
@@ -1548,6 +1602,16 @@ export class FlowEngine {
             return this.sampleSpread(estimated.meanMs, estimated.spread);
         }
         const spec = this.operationSpecs.get(ctx.kind);
+        /*
+         * **현장이 정한 시간이 원천 명세를 이긴다** — 원천 사본의 값이 낡았을 때 고칠 자리가 그것뿐이다
+         * (ADR-0034: 우리가 정한 값이 원천이 그려 준 값을 이긴다). 변동은 명세 행이 말한 것을 그대로 쓴다 —
+         * 평균만 우리가 고쳤다고 퍼짐을 0 으로 만들면 줄이 사라진다.
+         */
+        const local = this.localDurations.get(ctx.kind);
+        if (local !== undefined) {
+            this.noteSpecUse(ctx.kind, 'declared');
+            return this.applyVariability(local, spec?.variability);
+        }
         const declared = parseIsoDuration(spec?.duration);
         if (declared === undefined) {
             this.noteSpecUse(ctx.kind, 'default');

package/dist-cjs/index.cjs

@@ -55,6 +55,7 @@ __export(index_exports, {
   MES_PRODUCT_GTINS: () => MES_PRODUCT_GTINS,
   MES_TYPES: () => MES_TYPES,
   MesKernel: () => MesKernel,
+  OPERATION_PROPERTY: () => OPERATION_PROPERTY,
   OP_EVENT: () => OP_EVENT,
   OP_PARAM: () => OP_PARAM,
   ObservedReducer: () => ObservedReducer,
@@ -2963,6 +2964,10 @@ var ATTENTION_PROPERTY = {
   scrapMinSamples: "attention.scrapMinSamples"
 };
 var ATTENTION_DEFAULTS = { congestionPct: 90, scrapPct: 15, scrapMinSamples: 10 };
+var OPERATION_PROPERTY = {
+  /** 그 현장에서 이 공정이 걸리는 시간 — 실측이 없을 때 상수를 대신한다. */
+  duration: "operation.duration"
+};
 function deriveAttentions(view, acked, nowIso, thresholds) {
   const out = [];
   for (const m of view.equipment) {
@@ -3163,6 +3168,13 @@ var FlowEngine = class {
    * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
    */
   operationSpecs = /* @__PURE__ */ new Map();
+  /**
+   * 현장이 선언한 소요시간(작업 종류 → ms) — `declareDurations` 로 들어온다.
+   *
+   * 명세 행과 **따로** 두는 이유: 행이 없는 종류에도 시간을 줄 수 있어야 하고(창고·야드 트윈에는 행이
+   * 없다), 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다.
+   */
+  localDurations = /* @__PURE__ */ new Map();
   /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
   observer;
   /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
@@ -4170,6 +4182,37 @@ var FlowEngine = class {
   loadOperations(ops = []) {
     for (const o of ops) if (o?.key) this.operationSpecs.set(o.key, o);
   }
+  /**
+   * **현장이 정한 소요시간** — 종류별로 시간만 받는다(2026-08-18).
+   *
+   * ── 왜 명세 행과 따로 받나 ──────────────────────────────────────────────────
+   * 창고·야드 트윈에는 오퍼레이션 명세 행이 **아예 없다**(실측: 35개 트윈 중 WMS·YMS 전부 0개). 그런데
+   * 그 트윈들도 `putaway`·`pick`·`spot`·`dwell` 을 돌리고, 시간은 커널 상수에서 온다 — 그 현장이 실제로
+   * 몇 분 걸리는지 말할 문이 없었다.
+   *
+   * 명세 행을 지어 만들 수는 없다: `OperationDef` 는 `label`·`intent` 를 요구하고(ISA-95
+   * `OperationsSegment`), 그 둘은 **지어내면 다른 답까지 오염시킨다**(`capacity()`·능력 보고가 의도별로
+   * 자원을 센다). 「몇 분 걸리나」를 말하려고 「무슨 종류의 작업인가」를 발명하지 않는다.
+   *
+   * ── 순서: 실측 > 현장 선언 > 원천 명세 > 상수 ──────────────────────────────
+   * 이력에서 배운 값이 가장 강하고(그 현장이 실제로 그랬다), 그다음이 **이 선언**이다 — 원천 명세보다
+   * 이긴다(원천 사본의 값이 낡았을 때 고칠 자리가 여기다). 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
+   *
+   * ── 조용히 버리지 않는다 ────────────────────────────────────────────────────
+   * 읽을 수 없는 값은 던진다. 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 도는데,
+   * 그 어긋남을 아무도 볼 수 없다(이 시스템에서 가장 비싼 종류의 침묵이다).
+   */
+  declareDurations(durations) {
+    for (const [kind, text] of Object.entries(durations ?? {})) {
+      const key = String(kind ?? "").trim();
+      if (!key) throw new Error("declareDurations: an operation kind is empty \u2014 say which operation the duration belongs to");
+      const ms2 = parseIsoDuration(text);
+      if (ms2 === void 0)
+        throw new Error(`declareDurations: "${text}" is not an ISO 8601 duration (operation "${key}") \u2014 the value would be dropped without a trace`);
+      if (ms2 <= 0) throw new Error(`declareDurations: operation "${key}" cannot take ${ms2}ms \u2014 a task with no duration never finishes`);
+      this.localDurations.set(key, ms2);
+    }
+  }
   /**
    * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
    * 생산 정의를 가진 커널이 override 해서 자기 라우트를 답한다.
@@ -4271,10 +4314,12 @@ var FlowEngine = class {
     return out;
   }
   /**
-   * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 명세(ISA-95 Duration + 변동) → ③ 도메인 상수.**
+   * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 현장 선언(`declareDurations`) →
+   * ③ 명세(ISA-95 Duration + 변동) → ④ 도메인 상수.**
    *
    * 이 순서인 이유: 실측에서 배운 값이 선언값을 이기고, 선언값이 우리가 코드에 고정한 상수를 이긴다.
-   * 셋 중 무엇을 썼는지는 `specCoverage()` 로 드러낸다 — 상수를 쓴 것이 조용히 넘어가지 않게.
+   * 선언이 둘로 갈리는 이유는 권위다 — **현장이 정한 값**이 원천이 그려 준 명세를 이긴다(ADR-0034).
+   * 무엇을 썼는지는 `specCoverage()` 로 드러낸다 — 상수를 쓴 것이 조용히 넘어가지 않게.
    * "얼마"만 소비하고 "경로"는 씬이 소유한다(좌표-free 유지).
    */
   durationOf(ctx, fallbackMs) {
@@ -4288,6 +4333,11 @@ var FlowEngine = class {
       return this.sampleSpread(estimated.meanMs, estimated.spread);
     }
     const spec = this.operationSpecs.get(ctx.kind);
+    const local = this.localDurations.get(ctx.kind);
+    if (local !== void 0) {
+      this.noteSpecUse(ctx.kind, "declared");
+      return this.applyVariability(local, spec?.variability);
+    }
     const declared = parseIsoDuration(spec?.duration);
     if (declared === void 0) {
       this.noteSpecUse(ctx.kind, "default");
@@ -7276,6 +7326,7 @@ function retiredVocabularyIn(line) {
   MES_PRODUCT_GTINS,
   MES_TYPES,
   MesKernel,
+  OPERATION_PROPERTY,
   OP_EVENT,
   OP_PARAM,
   ObservedReducer,

package/package.json

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