@operato/twin-kernel 0.7.29 → 0.7.31

package/dist/flow-engine.d.ts

@@ -248,6 +248,15 @@ export declare const ATTENTION_DEFAULTS: {
 export declare const OPERATION_PROPERTY: {
     /** 그 현장에서 이 공정이 걸리는 시간 — 실측이 없을 때 상수를 대신한다. */
     readonly duration: "operation.duration";
+    /**
+     * 양품률 — 이 공정을 지난 것 중 몇이 양품인가. **커널이 읽는 값은 0..1** 이다(`OP_PARAM.yield`).
+     *
+     * 기본값이 코드 상수(0.8)였고, 그 상수가 불량 과다 주목 신호까지 만들었다 — 현장이 자기 수를 말할
+     * 자리가 필요하다. 사람이 넣는 단위(퍼센트)와 커널이 읽는 값(비율)이 다르므로 환산은 호스트가 한다.
+     */
+    readonly yield: "operation.yield";
+    /** 셋업·체인지오버 시간 — 가동 앞에 붙는다(`OP_PARAM.setupDuration`, ISO 8601). */
+    readonly setupDuration: "operation.setupDuration";
 };
 /** 판정에 쓸 기준 — 대상별 선언이 있으면 그것, 없으면 기본값(그 사실을 함께 든다). */
 export interface AttentionThresholds {
@@ -366,6 +375,13 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 없다), 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다.
      */
     protected localDurations: Map<string, number>;
+    /**
+     * 현장이 선언한 공정 모수(작업 종류 → 모수 id → 값) — `declareParameters` 로 들어온다.
+     *
+     * 값은 **표준 표기 그대로** 든다(ISA-95 `Parameter.Value.ValueString`): 수율은 0..1, 셋업은 ISO 8601.
+     * 읽는 쪽(`paramNumber`·`paramDuration`)이 명세 행보다 이것을 먼저 본다.
+     */
+    protected localParams: Map<string, Map<string, string>>;
     /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
     private observer?;
     /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
@@ -713,6 +729,23 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 그 어긋남을 아무도 볼 수 없다(이 시스템에서 가장 비싼 종류의 침묵이다).
      */
     declareDurations(durations: Record<string, IsoDuration> | undefined | null): void;
+    /**
+     * **현장이 정한 공정 모수** — 수율·셋업처럼 「얼마나 성공하나·바꾸는 데 얼마나 걸리나」 (2026-08-19).
+     *
+     * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+     * 양품률의 기본값은 커널 소스의 상수 0.8 이었다. 그 상수는 조용하지 않다: **불량 판정(주목 신호)까지
+     * 만든다** — 초기 라인이든 성숙한 라인이든 같은 0.8 로 굴러가고, 화면은 그 결과를 사실처럼 보인다.
+     * 셋업도 같다(기본 상수). 현장이 자기 수를 말할 문이 없었다.
+     *
+     * ── 소요시간과 같은 규율 ────────────────────────────────────────────────────
+     *  · 값은 **표준 표기 그대로** 받는다(ISA-95 `Parameter.Value.ValueString`): 수율 0..1, 셋업 ISO 8601.
+     *    퍼센트·분 같은 사람 단위를 커널이 알 필요는 없다 — 그 환산은 값을 받는 쪽(호스트)이 한다.
+     *  · **현장 선언이 원천 명세를 이긴다**(ADR-0034) — 원천 사본이 낡았을 때 고칠 자리가 그것뿐이다.
+     *  · 명세 행이 없는 종류에도 얹힌다 — 행을 지어 만들면 지어낸 `intent` 가 능력 계산을 오염시킨다.
+     *  · 무엇을 썼는지는 `specCoverage()` 의 `parameters` 가 그대로 밝힌다.
+     *  · 빈 이름·빈 값은 **던진다**: 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 돈다.
+     */
+    declareParameters(params: Record<string, Record<string, string | number>> | undefined | null): void;
     /**
      * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
      * 생산 정의를 가진 커널이 override 해서 자기 라우트를 답한다.
@@ -791,6 +824,13 @@ export declare abstract class FlowEngine implements TwinKernel {
     protected paramNumber(opKey: string, id: string): number | undefined;
     /** 명세 모수(기간) — ISO 8601 문자열을 밀리초로. 선언 없으면 undefined. */
     protected paramDuration(opKey: string, id: string): number | undefined;
+    /**
+     * 모수 값 한 개 — **현장이 정한 것이 원천 명세를 이긴다**(소요시간과 같은 순서: ADR-0034).
+     *
+     * 두 읽기(수·기간)가 같은 자리에서 값을 얻어야 우선순위가 한 벌로 남는다 — 예전에는 각자 명세 행만
+     * 뒤졌고, 그래서 현장 선언을 얹을 자리가 아예 없었다.
+     */
+    private paramValue;
     private noteSpecUse;
     private noteParamUse;
     /**

package/dist/flow-engine.js

@@ -77,7 +77,16 @@ export const ATTENTION_DEFAULTS = { congestionPct: 90, scrapPct: 15, scrapMinSam
  */
 export const OPERATION_PROPERTY = {
     /** 그 현장에서 이 공정이 걸리는 시간 — 실측이 없을 때 상수를 대신한다. */
-    duration: 'operation.duration'
+    duration: 'operation.duration',
+    /**
+     * 양품률 — 이 공정을 지난 것 중 몇이 양품인가. **커널이 읽는 값은 0..1** 이다(`OP_PARAM.yield`).
+     *
+     * 기본값이 코드 상수(0.8)였고, 그 상수가 불량 과다 주목 신호까지 만들었다 — 현장이 자기 수를 말할
+     * 자리가 필요하다. 사람이 넣는 단위(퍼센트)와 커널이 읽는 값(비율)이 다르므로 환산은 호스트가 한다.
+     */
+    yield: 'operation.yield',
+    /** 셋업·체인지오버 시간 — 가동 앞에 붙는다(`OP_PARAM.setupDuration`, ISO 8601). */
+    setupDuration: 'operation.setupDuration'
 };
 export function deriveAttentions(view, acked, 
 /** 지금(ISO) — 납기 판정에 필요하다. **주지 않으면 지연을 판정하지 않는다**(모르면 판단하지 않는다). */
@@ -330,6 +339,13 @@ export class FlowEngine {
      * 없다), 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다.
      */
     localDurations = new Map();
+    /**
+     * 현장이 선언한 공정 모수(작업 종류 → 모수 id → 값) — `declareParameters` 로 들어온다.
+     *
+     * 값은 **표준 표기 그대로** 든다(ISA-95 `Parameter.Value.ValueString`): 수율은 0..1, 셋업은 ISO 8601.
+     * 읽는 쪽(`paramNumber`·`paramDuration`)이 명세 행보다 이것을 먼저 본다.
+     */
+    localParams = new Map();
     /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
     observer;
     /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
@@ -1477,6 +1493,40 @@ export class FlowEngine {
             this.localDurations.set(key, ms);
         }
     }
+    /**
+     * **현장이 정한 공정 모수** — 수율·셋업처럼 「얼마나 성공하나·바꾸는 데 얼마나 걸리나」 (2026-08-19).
+     *
+     * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+     * 양품률의 기본값은 커널 소스의 상수 0.8 이었다. 그 상수는 조용하지 않다: **불량 판정(주목 신호)까지
+     * 만든다** — 초기 라인이든 성숙한 라인이든 같은 0.8 로 굴러가고, 화면은 그 결과를 사실처럼 보인다.
+     * 셋업도 같다(기본 상수). 현장이 자기 수를 말할 문이 없었다.
+     *
+     * ── 소요시간과 같은 규율 ────────────────────────────────────────────────────
+     *  · 값은 **표준 표기 그대로** 받는다(ISA-95 `Parameter.Value.ValueString`): 수율 0..1, 셋업 ISO 8601.
+     *    퍼센트·분 같은 사람 단위를 커널이 알 필요는 없다 — 그 환산은 값을 받는 쪽(호스트)이 한다.
+     *  · **현장 선언이 원천 명세를 이긴다**(ADR-0034) — 원천 사본이 낡았을 때 고칠 자리가 그것뿐이다.
+     *  · 명세 행이 없는 종류에도 얹힌다 — 행을 지어 만들면 지어낸 `intent` 가 능력 계산을 오염시킨다.
+     *  · 무엇을 썼는지는 `specCoverage()` 의 `parameters` 가 그대로 밝힌다.
+     *  · 빈 이름·빈 값은 **던진다**: 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 돈다.
+     */
+    declareParameters(params) {
+        for (const [kind, entries] of Object.entries(params ?? {})) {
+            const key = String(kind ?? '').trim();
+            if (!key)
+                throw new Error('declareParameters: an operation kind is empty — say which operation the parameter belongs to');
+            for (const [id, value] of Object.entries(entries ?? {})) {
+                const paramId = String(id ?? '').trim();
+                if (!paramId)
+                    throw new Error(`declareParameters: operation "${key}" has a parameter with no id — the value would never be read`);
+                const text = String(value ?? '').trim();
+                if (!text)
+                    throw new Error(`declareParameters: "${key}.${paramId}" has no value — an empty parameter is not a declaration`);
+                const bucket = this.localParams.get(key) ?? new Map();
+                bucket.set(paramId, text);
+                this.localParams.set(key, bucket);
+            }
+        }
+    }
     /**
      * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
      * 생산 정의를 가진 커널이 override 해서 자기 라우트를 답한다.
@@ -1659,10 +1709,10 @@ export class FlowEngine {
     }
     /** 명세 모수(숫자) — 선언 없으면 undefined(0 으로 꾸미지 않는다). 소비처가 기본값을 정한다. */
     paramNumber(opKey, id) {
-        const p = this.operationSpecs.get(opKey)?.parameters?.find(x => x.id === id);
-        if (!p)
+        const raw = this.paramValue(opKey, id);
+        if (raw === undefined)
             return undefined;
-        const n = Number(p.value);
+        const n = Number(raw);
         if (!Number.isFinite(n))
             return undefined;
         this.noteParamUse(opKey, id);
@@ -1670,12 +1720,23 @@ export class FlowEngine {
     }
     /** 명세 모수(기간) — ISO 8601 문자열을 밀리초로. 선언 없으면 undefined. */
     paramDuration(opKey, id) {
-        const p = this.operationSpecs.get(opKey)?.parameters?.find(x => x.id === id);
-        const ms = parseIsoDuration(p?.value);
+        const ms = parseIsoDuration(this.paramValue(opKey, id));
         if (ms !== undefined)
             this.noteParamUse(opKey, id);
         return ms;
     }
+    /**
+     * 모수 값 한 개 — **현장이 정한 것이 원천 명세를 이긴다**(소요시간과 같은 순서: ADR-0034).
+     *
+     * 두 읽기(수·기간)가 같은 자리에서 값을 얻어야 우선순위가 한 벌로 남는다 — 예전에는 각자 명세 행만
+     * 뒤졌고, 그래서 현장 선언을 얹을 자리가 아예 없었다.
+     */
+    paramValue(opKey, id) {
+        const local = this.localParams.get(opKey)?.get(id);
+        if (local !== undefined)
+            return local;
+        return this.operationSpecs.get(opKey)?.parameters?.find(x => x.id === id)?.value;
+    }
     noteSpecUse(kind, duration, variability) {
         const cur = this.specUse.get(kind);
         if (cur) {

package/dist-cjs/index.cjs

@@ -2966,7 +2966,16 @@ var ATTENTION_PROPERTY = {
 var ATTENTION_DEFAULTS = { congestionPct: 90, scrapPct: 15, scrapMinSamples: 10 };
 var OPERATION_PROPERTY = {
   /** 그 현장에서 이 공정이 걸리는 시간 — 실측이 없을 때 상수를 대신한다. */
-  duration: "operation.duration"
+  duration: "operation.duration",
+  /**
+   * 양품률 — 이 공정을 지난 것 중 몇이 양품인가. **커널이 읽는 값은 0..1** 이다(`OP_PARAM.yield`).
+   *
+   * 기본값이 코드 상수(0.8)였고, 그 상수가 불량 과다 주목 신호까지 만들었다 — 현장이 자기 수를 말할
+   * 자리가 필요하다. 사람이 넣는 단위(퍼센트)와 커널이 읽는 값(비율)이 다르므로 환산은 호스트가 한다.
+   */
+  yield: "operation.yield",
+  /** 셋업·체인지오버 시간 — 가동 앞에 붙는다(`OP_PARAM.setupDuration`, ISO 8601). */
+  setupDuration: "operation.setupDuration"
 };
 function deriveAttentions(view, acked, nowIso, thresholds) {
   const out = [];
@@ -3175,6 +3184,13 @@ var FlowEngine = class {
    * 없다), 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다.
    */
   localDurations = /* @__PURE__ */ new Map();
+  /**
+   * 현장이 선언한 공정 모수(작업 종류 → 모수 id → 값) — `declareParameters` 로 들어온다.
+   *
+   * 값은 **표준 표기 그대로** 든다(ISA-95 `Parameter.Value.ValueString`): 수율은 0..1, 셋업은 ISO 8601.
+   * 읽는 쪽(`paramNumber`·`paramDuration`)이 명세 행보다 이것을 먼저 본다.
+   */
+  localParams = /* @__PURE__ */ new Map();
   /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
   observer;
   /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
@@ -4213,6 +4229,37 @@ var FlowEngine = class {
       this.localDurations.set(key, ms2);
     }
   }
+  /**
+   * **현장이 정한 공정 모수** — 수율·셋업처럼 「얼마나 성공하나·바꾸는 데 얼마나 걸리나」 (2026-08-19).
+   *
+   * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+   * 양품률의 기본값은 커널 소스의 상수 0.8 이었다. 그 상수는 조용하지 않다: **불량 판정(주목 신호)까지
+   * 만든다** — 초기 라인이든 성숙한 라인이든 같은 0.8 로 굴러가고, 화면은 그 결과를 사실처럼 보인다.
+   * 셋업도 같다(기본 상수). 현장이 자기 수를 말할 문이 없었다.
+   *
+   * ── 소요시간과 같은 규율 ────────────────────────────────────────────────────
+   *  · 값은 **표준 표기 그대로** 받는다(ISA-95 `Parameter.Value.ValueString`): 수율 0..1, 셋업 ISO 8601.
+   *    퍼센트·분 같은 사람 단위를 커널이 알 필요는 없다 — 그 환산은 값을 받는 쪽(호스트)이 한다.
+   *  · **현장 선언이 원천 명세를 이긴다**(ADR-0034) — 원천 사본이 낡았을 때 고칠 자리가 그것뿐이다.
+   *  · 명세 행이 없는 종류에도 얹힌다 — 행을 지어 만들면 지어낸 `intent` 가 능력 계산을 오염시킨다.
+   *  · 무엇을 썼는지는 `specCoverage()` 의 `parameters` 가 그대로 밝힌다.
+   *  · 빈 이름·빈 값은 **던진다**: 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 돈다.
+   */
+  declareParameters(params) {
+    for (const [kind, entries] of Object.entries(params ?? {})) {
+      const key = String(kind ?? "").trim();
+      if (!key) throw new Error("declareParameters: an operation kind is empty \u2014 say which operation the parameter belongs to");
+      for (const [id, value] of Object.entries(entries ?? {})) {
+        const paramId = String(id ?? "").trim();
+        if (!paramId) throw new Error(`declareParameters: operation "${key}" has a parameter with no id \u2014 the value would never be read`);
+        const text = String(value ?? "").trim();
+        if (!text) throw new Error(`declareParameters: "${key}.${paramId}" has no value \u2014 an empty parameter is not a declaration`);
+        const bucket = this.localParams.get(key) ?? /* @__PURE__ */ new Map();
+        bucket.set(paramId, text);
+        this.localParams.set(key, bucket);
+      }
+    }
+  }
   /**
    * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
    * 생산 정의를 가진 커널이 override 해서 자기 라우트를 답한다.
@@ -4377,20 +4424,30 @@ var FlowEngine = class {
   }
   /** 명세 모수(숫자) — 선언 없으면 undefined(0 으로 꾸미지 않는다). 소비처가 기본값을 정한다. */
   paramNumber(opKey, id) {
-    const p = this.operationSpecs.get(opKey)?.parameters?.find((x) => x.id === id);
-    if (!p) return void 0;
-    const n = Number(p.value);
+    const raw = this.paramValue(opKey, id);
+    if (raw === void 0) return void 0;
+    const n = Number(raw);
     if (!Number.isFinite(n)) return void 0;
     this.noteParamUse(opKey, id);
     return n;
   }
   /** 명세 모수(기간) — ISO 8601 문자열을 밀리초로. 선언 없으면 undefined. */
   paramDuration(opKey, id) {
-    const p = this.operationSpecs.get(opKey)?.parameters?.find((x) => x.id === id);
-    const ms2 = parseIsoDuration(p?.value);
+    const ms2 = parseIsoDuration(this.paramValue(opKey, id));
     if (ms2 !== void 0) this.noteParamUse(opKey, id);
     return ms2;
   }
+  /**
+   * 모수 값 한 개 — **현장이 정한 것이 원천 명세를 이긴다**(소요시간과 같은 순서: ADR-0034).
+   *
+   * 두 읽기(수·기간)가 같은 자리에서 값을 얻어야 우선순위가 한 벌로 남는다 — 예전에는 각자 명세 행만
+   * 뒤졌고, 그래서 현장 선언을 얹을 자리가 아예 없었다.
+   */
+  paramValue(opKey, id) {
+    const local = this.localParams.get(opKey)?.get(id);
+    if (local !== void 0) return local;
+    return this.operationSpecs.get(opKey)?.parameters?.find((x) => x.id === id)?.value;
+  }
   noteSpecUse(kind, duration, variability) {
     const cur = this.specUse.get(kind);
     if (cur) {

package/package.json

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