@operato/twin-kernel 0.7.27 → 0.7.28

package/dist/flow-engine.d.ts

@@ -210,6 +210,39 @@ 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;
+};
+/** 판정에 쓸 기준 — 대상별 선언이 있으면 그것, 없으면 기본값(그 사실을 함께 든다). */
+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 +276,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;
@@ -491,6 +530,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) 검사에 쓴다.

package/dist/flow-engine.js

@@ -44,9 +44,38 @@ 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 };
 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 +96,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 +166,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 } }
@@ -1105,10 +1149,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) 검사에 쓴다.

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,
@@ -2952,7 +2954,16 @@ 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 };
+function deriveAttentions(view, acked, nowIso, thresholds) {
   const out = [];
   for (const m of view.equipment) {
     if (m.status === "down") {
@@ -2973,14 +2984,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 +3034,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 } }
@@ -3885,11 +3917,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) 검사에 쓴다.
@@ -7175,6 +7240,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,

package/package.json

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