@operato/twin-kernel 0.7.30 → 0.7.32

package/dist/contract.d.ts

@@ -1770,6 +1770,17 @@ export interface TaskStatusDelta {
     remainingMs?: number;
     /** 이 작업의 총 소요 예상(ms) — 진척의 분모. */
     durationMs?: number;
+    /**
+     * 품질 판정 결과 — **판정이 있었던 작업만** (2026-08-19).
+     *
+     * 왜 계약에 있나: 양품/불량은 설비 누적 카운터(종류를 모른다)와 EPCIS disposition(종류를 모른다)
+     * 에만 남아서, **「이 공정의 양품률이 얼마였나」를 저널에서 되짚을 수 없었다** — 재기동하면 종류별
+     * 품질 이력이 통째로 사라졌다. 판정이 일어나는 자리(작업 완료)에서 사실을 적는다.
+     *
+     * **없음은 「양품」이 아니라 「판정하지 않았다」**다(이동·체류에는 품질 판정이 없다). 그래서 소비처는
+     * 없는 것을 세지 않는다 — 모름을 양품으로 세면 양품률이 조용히 100% 로 올라간다.
+     */
+    outcome?: 'good' | 'scrap';
     /** 우선순위 — 나가지 않으면 미러가 배정 순서의 근거를 모른다(상태⊆이벤트). */
     priority?: number;
     startTime?: ISOTime;

package/dist/flow-engine.d.ts

@@ -174,6 +174,20 @@ export interface FlowTask {
      *   dwell:     자리에서 시간만 소비(무자원 체류·큐어링 — 즉시 진행, 자원 불요).
      */
     intent?: 'transport' | 'process' | 'dwell';
+    /**
+     * 이 작업의 **품질 판정 결과** — 판정이 있었을 때만 채운다 (2026-08-19).
+     *
+     * ── 왜 작업에 적나 ────────────────────────────────────────────────────────
+     * 양품/불량은 지금까지 두 곳에만 남았다: 설비 누적 카운터(`goodCount`·`scrapCount` — 종류를 모른다)와
+     * EPCIS disposition(`sellable`/`non_sellable` — 종류를 모른다). 그래서 **「이 공정의 양품률이 얼마였나」**
+     * 를 되짚을 방법이 저널에 없었다 — 재기동하면 종류별 품질 이력이 통째로 사라진다.
+     *
+     * 판정이 일어나는 자리는 작업 완료다(그때 종류·자원·결과를 함께 안다). 그러니 그 자리에서 적는다 —
+     * 나중에 자리·업무단계로 종류를 되짚는 추론을 만들지 않는다(설비 둘이 한 자리를 쓰면 조용히 틀린다).
+     *
+     * **없음은 「양품」이 아니라 「판정하지 않았다」**다(이동·체류에는 품질 판정이 없다).
+     */
+    outcome?: 'good' | 'scrap';
 }
 /** 오더 라인(멀티SKU) — 라인별 품목·잔량. 단일 SKU 오더 = 1 라인. */
 export interface OrderLine {
@@ -245,9 +259,29 @@ export declare const ATTENTION_DEFAULTS: {
  *
  * 이 값이 얹히는 대상은 **자리·설비가 아니라 공정 종류**다(`FlowTask.kind` = `OperationDef.key`).
  */
+/**
+ * 이력에서 배운 양품률 — 종류별 비율(0..1). **모르면 `undefined`**(0 을 답하지 않는다: 0 은 「전부 불량」이다).
+ *
+ * 소요시간 추정기와 같은 모양이다(무상태 시임, fork 가 참조를 공유). 표본이 모자란 종류는 추정기가
+ * 스스로 빼야 한다 — 두 건으로 만든 비율은 근거가 아니다.
+ */
+export interface YieldEstimator {
+    estimate(ctx: {
+        kind: string;
+    }): number | undefined;
+}
 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 {
@@ -354,6 +388,13 @@ export declare abstract class FlowEngine implements TwinKernel {
     protected policy: AllocationPolicy;
     /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
     durationEstimator?: DurationEstimator;
+    /**
+     * 양품률 시임(선택) — **이력에서 배운 수율.** 소요시간과 같은 자리·같은 규율이다 (2026-08-19).
+     *
+     * 없으면 선언값(현장→원천), 그것도 없으면 도메인 상수. 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
+     * 주입은 호스트가 한다(저널을 접는 쪽이 이력을 안다) — 커널은 시임만 든다.
+     */
+    yieldEstimator?: YieldEstimator;
     /**
      * 오퍼레이션 명세(선택) — 작업 종류(`FlowTask.kind` = `OperationDef.key`) → 소요·변동·모수.
      * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
@@ -366,6 +407,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 +761,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,7 +856,30 @@ 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;
+    /**
+     * 이 공정의 양품률 — **실측 > 현장 선언 > 원천 명세 > 도메인 상수** (2026-08-19).
+     *
+     * 소요시간(`durationOf`)과 같은 사다리다. 도메인 커널은 이 창구만 부르고 상수는 스스로 든다
+     * (`?? DEFAULT_YIELD`) — 상수를 쓴 사실은 `specCoverage()` 의 `parameterBasis` 가 밝힌다.
+     *
+     * 범위를 벗어난 실측은 쓰지 않는다: 비율이 아닌 값(0 미만·1 초과)은 이력 계산이 틀린 것이므로,
+     * 그것으로 시뮬을 굴리면 조용히 이상한 공장이 된다.
+     */
+    protected yieldOf(kind: string): number | undefined;
+    /**
+     * 모수 값 한 개 — **현장이 정한 것이 원천 명세를 이긴다**(소요시간과 같은 순서: ADR-0034).
+     *
+     * 두 읽기(수·기간)가 같은 자리에서 값을 얻어야 우선순위가 한 벌로 남는다 — 예전에는 각자 명세 행만
+     * 뒤졌고, 그래서 현장 선언을 얹을 자리가 아예 없었다.
+     */
+    private paramValue;
     private noteSpecUse;
+    /**
+     * 모수를 **무엇으로** 읽었나 — id 와 근거를 함께 적는다 (2026-08-19).
+     *
+     * 예전에는 id 만 세었다. 그래서 「수율을 읽었다」는 알 수 있어도 그것이 이력에서 배운 값인지 선언값인지
+     * 코드 상수인지 구별할 수 없었다 — 예측의 자격을 말하려면 그 구별이 필요하다(소요시간은 이미 구별한다).
+     */
     private noteParamUse;
     /**
      * 시뮬 명세 자기보고 — **어디까지 데이터로 말했고 어디부터 우리가 코드에 고정한 상수인가.**
@@ -805,6 +893,8 @@ export declare abstract class FlowEngine implements TwinKernel {
             duration: 'measured' | 'declared' | 'default';
             variability?: string;
             parameters: string[];
+            /** 그 모수를 무엇으로 읽었나(`id → measured|declared`) — 없는 id 는 상수를 썼다는 뜻이다. */
+            parameterBasis?: Record<string, 'measured' | 'declared'>;
         }[];
         /** 이력·계산에서 온 소요(추정기) — 선언값보다 강한 근거. */
         measuredDurations: number;

package/dist/flow-engine.js

@@ -12,6 +12,7 @@
 import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf } from "./contract.js";
 import { ObservedReducer } from "./observed-reducer.js";
 import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR, CBV_BIZSTEP } from "./epcis.js";
+import { OP_PARAM } from "./domain-definition.js";
 import { parseIsoDuration } from "./iso-duration.js";
 import { analyzeCapacity } from "./capacity.js";
 import { operationsCapabilityOf } from "./operations-capability.js";
@@ -67,17 +68,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'
+    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) — 납기 판정에 필요하다. **주지 않으면 지연을 판정하지 않는다**(모르면 판단하지 않는다). */
@@ -318,6 +320,13 @@ export class FlowEngine {
     policy;
     /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
     durationEstimator;
+    /**
+     * 양품률 시임(선택) — **이력에서 배운 수율.** 소요시간과 같은 자리·같은 규율이다 (2026-08-19).
+     *
+     * 없으면 선언값(현장→원천), 그것도 없으면 도메인 상수. 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
+     * 주입은 호스트가 한다(저널을 접는 쪽이 이력을 안다) — 커널은 시임만 든다.
+     */
+    yieldEstimator;
     /**
      * 오퍼레이션 명세(선택) — 작업 종류(`FlowTask.kind` = `OperationDef.key`) → 소요·변동·모수.
      * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
@@ -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 직전에 한 번만 옮긴다. */
@@ -1229,7 +1245,10 @@ export class FlowEngine {
         clone.durationEstimator = this.durationEstimator; // 무상태 시임 — 참조 공유(policy 와 동형)
         /* 명세는 불변(정의) → 참조 공유. 사용 기록은 fork 자기 것(무엇을 기본값으로 굴렸는지 fork 별로 다르다). */
         clone.operationSpecs = this.operationSpecs;
-        clone.specUse = new Map([...this.specUse.entries()].map(([k, u]) => [k, { duration: u.duration, variability: u.variability, params: new Set(u.params) }]));
+        clone.specUse = new Map([...this.specUse.entries()].map(([k, u]) => [
+            k,
+            { duration: u.duration, variability: u.variability, params: new Set(u.params), paramBasis: new Map(u.paramBasis) }
+        ]));
         return clone;
     }
     /**
@@ -1477,6 +1496,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 +1712,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 +1723,40 @@ 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;
     }
+    /**
+     * 이 공정의 양품률 — **실측 > 현장 선언 > 원천 명세 > 도메인 상수** (2026-08-19).
+     *
+     * 소요시간(`durationOf`)과 같은 사다리다. 도메인 커널은 이 창구만 부르고 상수는 스스로 든다
+     * (`?? DEFAULT_YIELD`) — 상수를 쓴 사실은 `specCoverage()` 의 `parameterBasis` 가 밝힌다.
+     *
+     * 범위를 벗어난 실측은 쓰지 않는다: 비율이 아닌 값(0 미만·1 초과)은 이력 계산이 틀린 것이므로,
+     * 그것으로 시뮬을 굴리면 조용히 이상한 공장이 된다.
+     */
+    yieldOf(kind) {
+        const measured = this.yieldEstimator?.estimate({ kind });
+        if (typeof measured === 'number' && measured >= 0 && measured <= 1) {
+            this.noteParamUse(kind, OP_PARAM.yield, 'measured');
+            return measured;
+        }
+        return this.paramNumber(kind, OP_PARAM.yield);
+    }
+    /**
+     * 모수 값 한 개 — **현장이 정한 것이 원천 명세를 이긴다**(소요시간과 같은 순서: 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) {
@@ -1684,14 +1765,22 @@ export class FlowEngine {
                 cur.variability = variability;
             return;
         }
-        this.specUse.set(kind, { duration, ...(variability ? { variability } : {}), params: new Set() });
+        this.specUse.set(kind, { duration, ...(variability ? { variability } : {}), params: new Set(), paramBasis: new Map() });
     }
-    noteParamUse(kind, id) {
+    /**
+     * 모수를 **무엇으로** 읽었나 — id 와 근거를 함께 적는다 (2026-08-19).
+     *
+     * 예전에는 id 만 세었다. 그래서 「수율을 읽었다」는 알 수 있어도 그것이 이력에서 배운 값인지 선언값인지
+     * 코드 상수인지 구별할 수 없었다 — 예측의 자격을 말하려면 그 구별이 필요하다(소요시간은 이미 구별한다).
+     */
+    noteParamUse(kind, id, basis = 'declared') {
         const cur = this.specUse.get(kind);
-        if (cur)
+        if (cur) {
             cur.params.add(id);
-        else
-            this.specUse.set(kind, { duration: 'default', params: new Set([id]) });
+            cur.paramBasis.set(id, basis);
+            return;
+        }
+        this.specUse.set(kind, { duration: 'default', params: new Set([id]), paramBasis: new Map([[id, basis]]) });
     }
     /**
      * 시뮬 명세 자기보고 — **어디까지 데이터로 말했고 어디부터 우리가 코드에 고정한 상수인가.**
@@ -1708,7 +1797,9 @@ export class FlowEngine {
                 kind,
                 duration: u.duration,
                 ...(variability ? { variability } : {}),
-                parameters: [...u.params].sort()
+                parameters: [...u.params].sort(),
+                /* 모수를 **무엇으로** 읽었나 — 읽은 것이 있을 때만 낸다(빈 표를 만들지 않는다). */
+                ...(u.paramBasis.size ? { parameterBasis: Object.fromEntries([...u.paramBasis.entries()].sort()) } : {})
             };
         });
         return {
@@ -1947,6 +2038,8 @@ export class FlowEngine {
             /* 실제 자재 이동 — 인원·설비와 같은 채널(실적을 한 곳에서 읽는다). */
             ...(t.materialActual?.length ? { materialActual: t.materialActual.map(r => ({ ...r })) } : {}),
             ...(t.durationMs ? { durationMs: t.durationMs } : {}),
+            /* 품질 판정이 있었으면 **그 자리에서** 실어 보낸다 — 없으면 필드를 만들지 않는다(모름≠양품). */
+            ...(t.outcome ? { outcome: t.outcome } : {}),
             ...(t.priority !== undefined ? { priority: t.priority } : {}),
             ...(t.startTime ? { startTime: t.startTime } : {}),
             ...(t.endTime ? { endTime: t.endTime } : {}),

package/dist/mes-kernel.js

@@ -229,7 +229,9 @@ export class MesKernel extends FlowEngine {
         // 마지막 스테이션(조립) → 완성차 (transform 1→1, disposition 으로 수율 loss → OEE 품질)
         const fgStore = this.locationByType('fg-store');
         const wip = order.allocated[0];
-        const good = this.rng() < (this.paramNumber(t.kind, OP_PARAM.yield) ?? DEFAULT_YIELD);
+        const good = this.rng() < (this.yieldOf(t.kind) ?? DEFAULT_YIELD);
+        /* 판정을 **작업에 적는다** — 그 자리에서 적어야 저널에 종류와 함께 남고, 이력에서 수율을 배울 수 있다. */
+        t.outcome = good ? 'good' : 'scrap';
         this.recordOutput(t.resource, good); // OEE 품질(마지막 자원별 양품/불량)
         const disp = good ? DISP.sellable : DISP.non_sellable;
         const outputEpc = sgtinUri(CP, product.ref, ++this.prodSeq);
@@ -352,7 +354,8 @@ export class MesKernel extends FlowEngine {
         }
         const fgStore = this.locationByType('fg-store');
         const wip = order.allocated[0];
-        const good = this.rng() < (this.paramNumber(t.kind, OP_PARAM.yield) ?? DEFAULT_YIELD);
+        const good = this.rng() < (this.yieldOf(t.kind) ?? DEFAULT_YIELD);
+        t.outcome = good ? 'good' : 'scrap'; // 같은 규율 — 판정은 일어난 자리에서 적는다
         this.recordOutput(t.resource, good);
         const disp = good ? DISP.sellable : DISP.non_sellable;
         const outEpc = this.serialOf(rc.outputs[0].material, ++this.prodSeq);

package/dist/task-fold.d.ts

@@ -23,6 +23,16 @@ export interface TaskFacets {
     order?: string;
     /** 가장 최근 도착 지점. 진행에 따라 바뀌므로 마지막 것이 사실이다. */
     location?: string;
+    /**
+     * 품질 판정 결과 — **판정이 있었을 때만** (2026-08-19).
+     *
+     * 이 축이 없으면 「이 공정의 양품률이 얼마였나」를 저널에서 되짚을 수 없다: 양품/불량은 설비 누적
+     * 카운터(종류 모름)와 EPCIS disposition(종류 모름)에만 남아 있었다. 판정은 작업 완료에서 일어나므로
+     * 그 자리에서 적고, 여기서 그대로 접는다.
+     *
+     * **없음은 「양품」이 아니라 「판정하지 않았다」**다(이동·체류에는 품질 판정이 없다).
+     */
+    outcome?: 'good' | 'scrap';
 }
 /** 작업 하나의 이정표 — 소비처가 이것으로 구간·지표를 만든다. */
 export interface TaskRecord {

package/dist/task-fold.js

@@ -46,6 +46,9 @@ export function foldTaskRecords(rows) {
             f.kind = d.kind;
         if (f.order === undefined && d.orderId)
             f.order = d.orderId;
+        /* 품질 판정은 완료 전이에 실려 온다 — 한 번 실린 값은 바뀌지 않는다(정정이 오면 마지막 것이 사실). */
+        if (d.outcome === 'good' || d.outcome === 'scrap')
+            f.outcome = d.outcome;
         const loc = d.toNode ?? d.fromNode;
         if (loc)
             f.location = loc;

package/dist-cjs/index.cjs

@@ -2630,6 +2630,7 @@ function foldTaskRecords(rows) {
     if (f.resource === void 0 && d.resourceRef) f.resource = d.resourceRef;
     if (f.kind === void 0 && d.kind) f.kind = d.kind;
     if (f.order === void 0 && d.orderId) f.order = d.orderId;
+    if (d.outcome === "good" || d.outcome === "scrap") f.outcome = d.outcome;
     const loc = d.toNode ?? d.fromNode;
     if (loc) f.location = loc;
     if (d.status === "created") rec.createdMs = at;
@@ -2966,7 +2967,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 = [];
@@ -3163,6 +3173,13 @@ var FlowEngine = class {
   policy;
   /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
   durationEstimator;
+  /**
+   * 양품률 시임(선택) — **이력에서 배운 수율.** 소요시간과 같은 자리·같은 규율이다 (2026-08-19).
+   *
+   * 없으면 선언값(현장→원천), 그것도 없으면 도메인 상수. 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
+   * 주입은 호스트가 한다(저널을 접는 쪽이 이력을 안다) — 커널은 시임만 든다.
+   */
+  yieldEstimator;
   /**
    * 오퍼레이션 명세(선택) — 작업 종류(`FlowTask.kind` = `OperationDef.key`) → 소요·변동·모수.
    * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
@@ -3175,6 +3192,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 직전에 한 번만 옮긴다. */
@@ -3987,7 +4011,12 @@ var FlowEngine = class {
     clone.rng.state = this.rng.state;
     clone.durationEstimator = this.durationEstimator;
     clone.operationSpecs = this.operationSpecs;
-    clone.specUse = new Map([...this.specUse.entries()].map(([k, u]) => [k, { duration: u.duration, variability: u.variability, params: new Set(u.params) }]));
+    clone.specUse = new Map(
+      [...this.specUse.entries()].map(([k, u]) => [
+        k,
+        { duration: u.duration, variability: u.variability, params: new Set(u.params), paramBasis: new Map(u.paramBasis) }
+      ])
+    );
     return clone;
   }
   /**
@@ -4213,6 +4242,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 +4437,47 @@ 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;
   }
+  /**
+   * 이 공정의 양품률 — **실측 > 현장 선언 > 원천 명세 > 도메인 상수** (2026-08-19).
+   *
+   * 소요시간(`durationOf`)과 같은 사다리다. 도메인 커널은 이 창구만 부르고 상수는 스스로 든다
+   * (`?? DEFAULT_YIELD`) — 상수를 쓴 사실은 `specCoverage()` 의 `parameterBasis` 가 밝힌다.
+   *
+   * 범위를 벗어난 실측은 쓰지 않는다: 비율이 아닌 값(0 미만·1 초과)은 이력 계산이 틀린 것이므로,
+   * 그것으로 시뮬을 굴리면 조용히 이상한 공장이 된다.
+   */
+  yieldOf(kind) {
+    const measured = this.yieldEstimator?.estimate({ kind });
+    if (typeof measured === "number" && measured >= 0 && measured <= 1) {
+      this.noteParamUse(kind, OP_PARAM.yield, "measured");
+      return measured;
+    }
+    return this.paramNumber(kind, OP_PARAM.yield);
+  }
+  /**
+   * 모수 값 한 개 — **현장이 정한 것이 원천 명세를 이긴다**(소요시간과 같은 순서: 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) {
@@ -4398,12 +4485,22 @@ var FlowEngine = class {
       if (variability) cur.variability = variability;
       return;
     }
-    this.specUse.set(kind, { duration, ...variability ? { variability } : {}, params: /* @__PURE__ */ new Set() });
+    this.specUse.set(kind, { duration, ...variability ? { variability } : {}, params: /* @__PURE__ */ new Set(), paramBasis: /* @__PURE__ */ new Map() });
   }
-  noteParamUse(kind, id) {
+  /**
+   * 모수를 **무엇으로** 읽었나 — id 와 근거를 함께 적는다 (2026-08-19).
+   *
+   * 예전에는 id 만 세었다. 그래서 「수율을 읽었다」는 알 수 있어도 그것이 이력에서 배운 값인지 선언값인지
+   * 코드 상수인지 구별할 수 없었다 — 예측의 자격을 말하려면 그 구별이 필요하다(소요시간은 이미 구별한다).
+   */
+  noteParamUse(kind, id, basis = "declared") {
     const cur = this.specUse.get(kind);
-    if (cur) cur.params.add(id);
-    else this.specUse.set(kind, { duration: "default", params: /* @__PURE__ */ new Set([id]) });
+    if (cur) {
+      cur.params.add(id);
+      cur.paramBasis.set(id, basis);
+      return;
+    }
+    this.specUse.set(kind, { duration: "default", params: /* @__PURE__ */ new Set([id]), paramBasis: /* @__PURE__ */ new Map([[id, basis]]) });
   }
   /**
    * 시뮬 명세 자기보고 — **어디까지 데이터로 말했고 어디부터 우리가 코드에 고정한 상수인가.**
@@ -4419,7 +4516,9 @@ var FlowEngine = class {
         kind,
         duration: u.duration,
         ...variability ? { variability } : {},
-        parameters: [...u.params].sort()
+        parameters: [...u.params].sort(),
+        /* 모수를 **무엇으로** 읽었나 — 읽은 것이 있을 때만 낸다(빈 표를 만들지 않는다). */
+        ...u.paramBasis.size ? { parameterBasis: Object.fromEntries([...u.paramBasis.entries()].sort()) } : {}
       };
     });
     return {
@@ -4644,6 +4743,8 @@ var FlowEngine = class {
       /* 실제 자재 이동 — 인원·설비와 같은 채널(실적을 한 곳에서 읽는다). */
       ...t.materialActual?.length ? { materialActual: t.materialActual.map((r) => ({ ...r })) } : {},
       ...t.durationMs ? { durationMs: t.durationMs } : {},
+      /* 품질 판정이 있었으면 **그 자리에서** 실어 보낸다 — 없으면 필드를 만들지 않는다(모름≠양품). */
+      ...t.outcome ? { outcome: t.outcome } : {},
       ...t.priority !== void 0 ? { priority: t.priority } : {},
       ...t.startTime ? { startTime: t.startTime } : {},
       ...t.endTime ? { endTime: t.endTime } : {},
@@ -6106,7 +6207,8 @@ var MesKernel = class extends FlowEngine {
     }
     const fgStore = this.locationByType("fg-store");
     const wip = order.allocated[0];
-    const good = this.rng() < (this.paramNumber(t.kind, OP_PARAM.yield) ?? DEFAULT_YIELD);
+    const good = this.rng() < (this.yieldOf(t.kind) ?? DEFAULT_YIELD);
+    t.outcome = good ? "good" : "scrap";
     this.recordOutput(t.resource, good);
     const disp = good ? DISP.sellable : DISP.non_sellable;
     const outputEpc = sgtinUri(CP2, product.ref, ++this.prodSeq);
@@ -6218,7 +6320,8 @@ var MesKernel = class extends FlowEngine {
     }
     const fgStore = this.locationByType("fg-store");
     const wip = order.allocated[0];
-    const good = this.rng() < (this.paramNumber(t.kind, OP_PARAM.yield) ?? DEFAULT_YIELD);
+    const good = this.rng() < (this.yieldOf(t.kind) ?? DEFAULT_YIELD);
+    t.outcome = good ? "good" : "scrap";
     this.recordOutput(t.resource, good);
     const disp = good ? DISP.sellable : DISP.non_sellable;
     const outEpc = this.serialOf(rc.outputs[0].material, ++this.prodSeq);

package/package.json

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