@operato/twin-kernel 0.7.27 → 0.7.29

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 {
@@ -210,6 +210,51 @@ interface Rng {
  * FlowEngine.computeAttentions(sim) 와 live projector 미러가 **공유**하는 계산 층(face2-inbound-live §1.1):
  * sim/live 가 같은 임계값·규칙을 쓴다. good/scrap 미제공(관측 상태에 없음)이면 scrap-high 는 자연 스킵(metric 층 갭).
  */
+/**
+ * 주의 판정의 **기준값 어휘** — 현장이 정하는 수다.
+ *
+ * ── 왜 선언으로 받나 (2026-08-18) ───────────────────────────────────────────
+ * 혼잡 90%·불량 15%는 **우리가 정한 수**였다(코드 상수). 그런데 통로를 95%로 채워 쓰는 창고는 그 기준에서
+ * 영구히 「병목」이고, 초기 라인(불량 20% 예상)은 계속 「불량 과다」로 운다. 경보가 소음이 되면 사람이
+ * 경보 자체를 읽지 않는다 — 그때 진짜 경보도 함께 묻힌다.
+ *
+ * 그래서 기준을 현장이 넣을 수 있게 하고, **넣지 않으면 기본값을 쓰되 그 사실을 밝힌다**(`basis`).
+ * 조용히 기본값을 진실처럼 두지 않는다.
+ *
+ * 퍼센트다: 90 이 90%이고 0.9 는 0.9%다(SOC 에서 한 번 겪은 함정 — 명세가 그 말을 한다).
+ */
+export declare const ATTENTION_PROPERTY: {
+    /** 자리의 혼잡 판정 기준(%) — 점유/용량이 이 값을 넘으면 병목으로 본다. */
+    readonly congestionRatio: "attention.congestionRatio";
+    /** 설비의 불량률 판정 기준(%) — 이 값을 넘으면 불량 과다로 본다. */
+    readonly scrapRate: "attention.scrapRate";
+    /** 불량률을 재기 시작할 최소 표본 수 — 적은 표본의 비율은 판정 근거가 못 된다. */
+    readonly scrapMinSamples: "attention.scrapMinSamples";
+};
+/** 선언이 없을 때 쓰는 기본값 — **드러내 둔다**(코드 안에 숨은 상수가 아니라 계약의 일부다). */
+export declare const ATTENTION_DEFAULTS: {
+    readonly congestionPct: 90;
+    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;
+    scrapPctOf?: (equipmentId: string) => number | undefined;
+    scrapMinSamplesOf?: (equipmentId: string) => number | undefined;
+}
 export declare function deriveAttentions(view: {
     equipment: {
         id: string;
@@ -243,7 +288,13 @@ export declare function deriveAttentions(view: {
     }[];
 }, acked?: ReadonlySet<string>, 
 /** 지금(ISO) — 납기 판정에 필요하다. **주지 않으면 지연을 판정하지 않는다**(모르면 판단하지 않는다). */
-nowIso?: ISOTime): Attention[];
+nowIso?: ISOTime, 
+/**
+ * 현장이 선언한 판정 기준 — 주지 않으면 기본값으로 판정하고 그 사실을 `params.basis` 로 밝힌다.
+ *
+ * 부르는 쪽이 모델에서 뽑아 넘긴다(이 함수는 순수하게 남는다 — 모델을 읽는 규칙이 두 곳이 되지 않게).
+ */
+thresholds?: AttentionThresholds): Attention[];
 /** OEE 계측 카운터 — sim 은 tick 으로 누적, live 는 실 텔레메트리 또는 이벤트 누적기가 채운다(face2-inbound-live §1.1). */
 export interface OeeCounters {
     runMs: number;
@@ -308,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 직전에 한 번만 옮긴다. */
@@ -491,6 +549,14 @@ export declare abstract class FlowEngine implements TwinKernel {
     getSnapshot(): StateSnapshot;
     protected computeAttentions(): Attention[];
     protected collectAttentions(): Attention[];
+    /**
+     * 현장이 선언한 판정 기준을 모델에서 뽑는다 — **규칙은 한 곳**(순수 함수는 모델을 읽지 않는다).
+     *
+     * 자리·설비의 속성에서 읽고, 없으면 `undefined` 를 돌려 기본값이 쓰이게 한다(그 사실은 판정 층이
+     * `basis` 로 밝힌다). 값이 수가 아니거나 범위를 벗어나면 **없는 것으로 본다** — 사람이 손으로 넣는
+     * 값이라 잘못 들어올 수 있고, 잘못된 기준으로 판정하는 것은 기본값보다 나쁘다.
+     */
+    protected attentionThresholds(): AttentionThresholds;
     /**
      * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
      * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 시뮬레이션해 forecast·발산(predicted vs actual) 검사에 쓴다.
@@ -626,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 해서 자기 라우트를 답한다.
@@ -680,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

@@ -44,9 +44,50 @@ function mulberry32(seed) {
  * FlowEngine.computeAttentions(sim) 와 live projector 미러가 **공유**하는 계산 층(face2-inbound-live §1.1):
  * sim/live 가 같은 임계값·규칙을 쓴다. good/scrap 미제공(관측 상태에 없음)이면 scrap-high 는 자연 스킵(metric 층 갭).
  */
+/**
+ * 주의 판정의 **기준값 어휘** — 현장이 정하는 수다.
+ *
+ * ── 왜 선언으로 받나 (2026-08-18) ───────────────────────────────────────────
+ * 혼잡 90%·불량 15%는 **우리가 정한 수**였다(코드 상수). 그런데 통로를 95%로 채워 쓰는 창고는 그 기준에서
+ * 영구히 「병목」이고, 초기 라인(불량 20% 예상)은 계속 「불량 과다」로 운다. 경보가 소음이 되면 사람이
+ * 경보 자체를 읽지 않는다 — 그때 진짜 경보도 함께 묻힌다.
+ *
+ * 그래서 기준을 현장이 넣을 수 있게 하고, **넣지 않으면 기본값을 쓰되 그 사실을 밝힌다**(`basis`).
+ * 조용히 기본값을 진실처럼 두지 않는다.
+ *
+ * 퍼센트다: 90 이 90%이고 0.9 는 0.9%다(SOC 에서 한 번 겪은 함정 — 명세가 그 말을 한다).
+ */
+export const ATTENTION_PROPERTY = {
+    /** 자리의 혼잡 판정 기준(%) — 점유/용량이 이 값을 넘으면 병목으로 본다. */
+    congestionRatio: 'attention.congestionRatio',
+    /** 설비의 불량률 판정 기준(%) — 이 값을 넘으면 불량 과다로 본다. */
+    scrapRate: 'attention.scrapRate',
+    /** 불량률을 재기 시작할 최소 표본 수 — 적은 표본의 비율은 판정 근거가 못 된다. */
+    scrapMinSamples: 'attention.scrapMinSamples'
+};
+/** 선언이 없을 때 쓰는 기본값 — **드러내 둔다**(코드 안에 숨은 상수가 아니라 계약의 일부다). */
+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) {
+nowIso, 
+/**
+ * 현장이 선언한 판정 기준 — 주지 않으면 기본값으로 판정하고 그 사실을 `params.basis` 로 밝힌다.
+ *
+ * 부르는 쪽이 모델에서 뽑아 넘긴다(이 함수는 순수하게 남는다 — 모델을 읽는 규칙이 두 곳이 되지 않게).
+ */
+thresholds) {
     // 언어 중립: kind + params(원시값) + 조치 code 만 방출. 사람이 읽는 title/detail/rationale/라벨은
     // 표현계층(클라 i18next)이 kind/code 로 렌더한다(무방언·다국어 — design/plans/i18n.md L3).
     const out = [];
@@ -67,12 +108,19 @@ nowIso) {
     for (const n of view.locations) {
         if ((n.capacity ?? 0) > 0) {
             const r = (n.occupancy ?? 0) / n.capacity;
-            if (r >= 0.9) {
+            /* 기준은 현장이 정한다 — 없으면 기본값이고, 어느 쪽인지 함께 낸다(조용히 기본값을 진실로 두지 않는다). */
+            const declaredPct = thresholds?.congestionPctOf?.(n.id);
+            const thresholdPct = declaredPct ?? ATTENTION_DEFAULTS.congestionPct;
+            if (r * 100 >= thresholdPct) {
                 const saturated = r >= 1;
                 out.push({
                     id: `bottleneck:${n.id}`, kind: 'bottleneck', severity: saturated ? 'high' : 'medium',
                     anchor: { locationId: n.id },
-                    params: { locationId: n.id, occupancy: n.occupancy ?? 0, capacity: n.capacity ?? 0, ratioPct: Math.round(r * 100), saturated: saturated ? 1 : 0 },
+                    params: {
+                        locationId: n.id, occupancy: n.occupancy ?? 0, capacity: n.capacity ?? 0, ratioPct: Math.round(r * 100),
+                        saturated: saturated ? 1 : 0,
+                        thresholdPct, basis: declaredPct === undefined ? 'default' : 'declared'
+                    },
                     recommendedActions: [{ code: 'advice.add-resource' }, { code: 'advice.downstream-priority' }]
                     // 권고만(command 없음) — 표현계층이 advice.* 코드로 렌더
                 });
@@ -130,13 +178,21 @@ nowIso) {
     }
     for (const m of view.equipment) {
         const total = (m.goodCount ?? 0) + (m.scrapCount ?? 0);
-        if (total >= 10) {
+        const declaredMin = thresholds?.scrapMinSamplesOf?.(m.id);
+        const minSamples = declaredMin ?? ATTENTION_DEFAULTS.scrapMinSamples;
+        if (total >= minSamples) {
             const rate = (m.scrapCount ?? 0) / total;
-            if (rate >= 0.15)
+            const declaredPct = thresholds?.scrapPctOf?.(m.id);
+            const thresholdPct = declaredPct ?? ATTENTION_DEFAULTS.scrapPct;
+            /* 「높음」은 기준의 두 배에서 — 기준이 현장의 것이면 그 두 배도 현장의 것이다(상수 두 벌을 두지 않는다). */
+            if (rate * 100 >= thresholdPct)
                 out.push({
-                    id: `scrap:${m.id}`, kind: 'scrap-high', severity: rate >= 0.3 ? 'high' : 'medium',
+                    id: `scrap:${m.id}`, kind: 'scrap-high', severity: rate * 100 >= thresholdPct * 2 ? 'high' : 'medium',
                     anchor: { moverId: m.id, locationId: m.location },
-                    params: { moverId: m.id, goodCount: m.goodCount ?? 0, scrapCount: m.scrapCount ?? 0, ratePct: Math.round(rate * 100) },
+                    params: {
+                        moverId: m.id, goodCount: m.goodCount ?? 0, scrapCount: m.scrapCount ?? 0, ratePct: Math.round(rate * 100),
+                        thresholdPct, basis: declaredPct === undefined ? 'default' : 'declared'
+                    },
                     recommendedActions: [
                         { code: 'act.hold-for-inspection', command: CMD.resourceHold, args: { resourceId: m.id } },
                         { code: 'act.reset-metrics', command: CMD.resourceResetMetrics, args: { resourceId: m.id } }
@@ -267,6 +323,13 @@ export class FlowEngine {
      * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
      */
     operationSpecs = new Map();
+    /**
+     * 현장이 선언한 소요시간(작업 종류 → ms) — `declareDurations` 로 들어온다.
+     *
+     * 명세 행과 **따로** 두는 이유: 행이 없는 종류에도 시간을 줄 수 있어야 하고(창고·야드 트윈에는 행이
+     * 없다), 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다.
+     */
+    localDurations = new Map();
     /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
     observer;
     /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
@@ -1105,10 +1168,40 @@ export class FlowEngine {
             locations: [...this.locations.values()],
             orders: [...this.orders.values()],
             tasks: [...this.tasks.values()]
-        }, this._acked, now // 지연 판정의 "지금" — 관측 중이면 마지막으로 들은 시각이다(§nowMs)
-        );
+        }, this._acked, now, // 지연 판정의 "지금" — 관측 중이면 마지막으로 들은 시각이다(§nowMs)
+        this.attentionThresholds());
         return out;
     }
+    /**
+     * 현장이 선언한 판정 기준을 모델에서 뽑는다 — **규칙은 한 곳**(순수 함수는 모델을 읽지 않는다).
+     *
+     * 자리·설비의 속성에서 읽고, 없으면 `undefined` 를 돌려 기본값이 쓰이게 한다(그 사실은 판정 층이
+     * `basis` 로 밝힌다). 값이 수가 아니거나 범위를 벗어나면 **없는 것으로 본다** — 사람이 손으로 넣는
+     * 값이라 잘못 들어올 수 있고, 잘못된 기준으로 판정하는 것은 기본값보다 나쁘다.
+     */
+    attentionThresholds() {
+        const pct = (props, id) => {
+            const raw = props?.find(p => p.id === id)?.value;
+            if (raw === undefined)
+                return undefined;
+            const n = Number(raw);
+            return Number.isFinite(n) && n > 0 && n <= 100 ? n : undefined;
+        };
+        const count = (props, id) => {
+            const raw = props?.find(p => p.id === id)?.value;
+            if (raw === undefined)
+                return undefined;
+            const n = Number(raw);
+            return Number.isFinite(n) && n >= 1 ? Math.floor(n) : undefined;
+        };
+        const locProps = new Map((this.boardDef?.locations ?? []).map(l => [l.id, l.properties]));
+        const eqProps = new Map(readBoardEquipment(this.boardDef ?? {}).map(e => [e.id, e.properties]));
+        return {
+            congestionPctOf: id => pct(locProps.get(id), ATTENTION_PROPERTY.congestionRatio),
+            scrapPctOf: id => pct(eqProps.get(id), ATTENTION_PROPERTY.scrapRate),
+            scrapMinSamplesOf: id => count(eqProps.get(id), ATTENTION_PROPERTY.scrapMinSamples)
+        };
+    }
     /**
      * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
      * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 시뮬레이션해 forecast·발산(predicted vs actual) 검사에 쓴다.
@@ -1351,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 해서 자기 라우트를 답한다.
@@ -1454,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) {
@@ -1474,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

@@ -19,6 +19,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ATTENTION_DEFAULTS: () => ATTENTION_DEFAULTS,
+  ATTENTION_PROPERTY: () => ATTENTION_PROPERTY,
   BIZSTEP: () => BIZSTEP,
   BTT: () => BTT,
   BTT_DELIVERY: () => BTT_DELIVERY,
@@ -53,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,
@@ -2952,7 +2955,20 @@ function mulberry32(seed) {
   } });
   return fn;
 }
-function deriveAttentions(view, acked, nowIso) {
+var ATTENTION_PROPERTY = {
+  /** 자리의 혼잡 판정 기준(%) — 점유/용량이 이 값을 넘으면 병목으로 본다. */
+  congestionRatio: "attention.congestionRatio",
+  /** 설비의 불량률 판정 기준(%) — 이 값을 넘으면 불량 과다로 본다. */
+  scrapRate: "attention.scrapRate",
+  /** 불량률을 재기 시작할 최소 표본 수 — 적은 표본의 비율은 판정 근거가 못 된다. */
+  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) {
     if (m.status === "down") {
@@ -2973,14 +2989,24 @@ function deriveAttentions(view, acked, nowIso) {
   for (const n of view.locations) {
     if ((n.capacity ?? 0) > 0) {
       const r = (n.occupancy ?? 0) / n.capacity;
-      if (r >= 0.9) {
+      const declaredPct = thresholds?.congestionPctOf?.(n.id);
+      const thresholdPct = declaredPct ?? ATTENTION_DEFAULTS.congestionPct;
+      if (r * 100 >= thresholdPct) {
         const saturated = r >= 1;
         out.push({
           id: `bottleneck:${n.id}`,
           kind: "bottleneck",
           severity: saturated ? "high" : "medium",
           anchor: { locationId: n.id },
-          params: { locationId: n.id, occupancy: n.occupancy ?? 0, capacity: n.capacity ?? 0, ratioPct: Math.round(r * 100), saturated: saturated ? 1 : 0 },
+          params: {
+            locationId: n.id,
+            occupancy: n.occupancy ?? 0,
+            capacity: n.capacity ?? 0,
+            ratioPct: Math.round(r * 100),
+            saturated: saturated ? 1 : 0,
+            thresholdPct,
+            basis: declaredPct === void 0 ? "default" : "declared"
+          },
           recommendedActions: [{ code: "advice.add-resource" }, { code: "advice.downstream-priority" }]
           // 권고만(command 없음) — 표현계층이 advice.* 코드로 렌더
         });
@@ -3013,14 +3039,25 @@ function deriveAttentions(view, acked, nowIso) {
   }
   for (const m of view.equipment) {
     const total = (m.goodCount ?? 0) + (m.scrapCount ?? 0);
-    if (total >= 10) {
+    const declaredMin = thresholds?.scrapMinSamplesOf?.(m.id);
+    const minSamples = declaredMin ?? ATTENTION_DEFAULTS.scrapMinSamples;
+    if (total >= minSamples) {
       const rate = (m.scrapCount ?? 0) / total;
-      if (rate >= 0.15) out.push({
+      const declaredPct = thresholds?.scrapPctOf?.(m.id);
+      const thresholdPct = declaredPct ?? ATTENTION_DEFAULTS.scrapPct;
+      if (rate * 100 >= thresholdPct) out.push({
         id: `scrap:${m.id}`,
         kind: "scrap-high",
-        severity: rate >= 0.3 ? "high" : "medium",
+        severity: rate * 100 >= thresholdPct * 2 ? "high" : "medium",
         anchor: { moverId: m.id, locationId: m.location },
-        params: { moverId: m.id, goodCount: m.goodCount ?? 0, scrapCount: m.scrapCount ?? 0, ratePct: Math.round(rate * 100) },
+        params: {
+          moverId: m.id,
+          goodCount: m.goodCount ?? 0,
+          scrapCount: m.scrapCount ?? 0,
+          ratePct: Math.round(rate * 100),
+          thresholdPct,
+          basis: declaredPct === void 0 ? "default" : "declared"
+        },
         recommendedActions: [
           { code: "act.hold-for-inspection", command: CMD.resourceHold, args: { resourceId: m.id } },
           { code: "act.reset-metrics", command: CMD.resourceResetMetrics, args: { resourceId: m.id } }
@@ -3131,6 +3168,13 @@ var FlowEngine = class {
    * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
    */
   operationSpecs = /* @__PURE__ */ new Map();
+  /**
+   * 현장이 선언한 소요시간(작업 종류 → ms) — `declareDurations` 로 들어온다.
+   *
+   * 명세 행과 **따로** 두는 이유: 행이 없는 종류에도 시간을 줄 수 있어야 하고(창고·야드 트윈에는 행이
+   * 없다), 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다.
+   */
+  localDurations = /* @__PURE__ */ new Map();
   /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
   observer;
   /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
@@ -3885,11 +3929,44 @@ var FlowEngine = class {
         tasks: [...this.tasks.values()]
       },
       this._acked,
-      now
+      now,
       // 지연 판정의 "지금" — 관측 중이면 마지막으로 들은 시각이다(§nowMs)
+      this.attentionThresholds()
     );
     return out;
   }
+  /**
+   * 현장이 선언한 판정 기준을 모델에서 뽑는다 — **규칙은 한 곳**(순수 함수는 모델을 읽지 않는다).
+   *
+   * 자리·설비의 속성에서 읽고, 없으면 `undefined` 를 돌려 기본값이 쓰이게 한다(그 사실은 판정 층이
+   * `basis` 로 밝힌다). 값이 수가 아니거나 범위를 벗어나면 **없는 것으로 본다** — 사람이 손으로 넣는
+   * 값이라 잘못 들어올 수 있고, 잘못된 기준으로 판정하는 것은 기본값보다 나쁘다.
+   */
+  attentionThresholds() {
+    const pct = (props, id) => {
+      const raw = props?.find((p) => p.id === id)?.value;
+      if (raw === void 0) return void 0;
+      const n = Number(raw);
+      return Number.isFinite(n) && n > 0 && n <= 100 ? n : void 0;
+    };
+    const count = (props, id) => {
+      const raw = props?.find((p) => p.id === id)?.value;
+      if (raw === void 0) return void 0;
+      const n = Number(raw);
+      return Number.isFinite(n) && n >= 1 ? Math.floor(n) : void 0;
+    };
+    const locProps = new Map(
+      (this.boardDef?.locations ?? []).map((l) => [l.id, l.properties])
+    );
+    const eqProps = new Map(
+      readBoardEquipment(this.boardDef ?? {}).map((e) => [e.id, e.properties])
+    );
+    return {
+      congestionPctOf: (id) => pct(locProps.get(id), ATTENTION_PROPERTY.congestionRatio),
+      scrapPctOf: (id) => pct(eqProps.get(id), ATTENTION_PROPERTY.scrapRate),
+      scrapMinSamplesOf: (id) => count(eqProps.get(id), ATTENTION_PROPERTY.scrapMinSamples)
+    };
+  }
   /**
    * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
    * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 시뮬레이션해 forecast·발산(predicted vs actual) 검사에 쓴다.
@@ -4105,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 해서 자기 라우트를 답한다.
@@ -4206,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) {
@@ -4223,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");
@@ -7175,6 +7290,8 @@ function retiredVocabularyIn(line) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ATTENTION_DEFAULTS,
+  ATTENTION_PROPERTY,
   BIZSTEP,
   BTT,
   BTT_DELIVERY,
@@ -7209,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.27",
+  "version": "0.7.29",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {