@operato/twin-kernel 0.7.31 → 0.7.33

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,6 +259,17 @@ 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";
@@ -363,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()` 가 밝힌다.
@@ -824,6 +856,16 @@ 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).
      *
@@ -832,6 +874,12 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     private paramValue;
     private noteSpecUse;
+    /**
+     * 모수를 **무엇으로** 읽었나 — id 와 근거를 함께 적는다 (2026-08-19).
+     *
+     * 예전에는 id 만 세었다. 그래서 「수율을 읽었다」는 알 수 있어도 그것이 이력에서 배운 값인지 선언값인지
+     * 코드 상수인지 구별할 수 없었다 — 예측의 자격을 말하려면 그 구별이 필요하다(소요시간은 이미 구별한다).
+     */
     private noteParamUse;
     /**
      * 시뮬 명세 자기보고 — **어디까지 데이터로 말했고 어디부터 우리가 코드에 고정한 상수인가.**
@@ -845,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,14 +68,6 @@ 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',
@@ -327,6 +320,13 @@ export class FlowEngine {
     policy;
     /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
     durationEstimator;
+    /**
+     * 양품률 시임(선택) — **이력에서 배운 수율.** 소요시간과 같은 자리·같은 규율이다 (2026-08-19).
+     *
+     * 없으면 선언값(현장→원천), 그것도 없으면 도메인 상수. 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
+     * 주입은 호스트가 한다(저널을 접는 쪽이 이력을 안다) — 커널은 시임만 든다.
+     */
+    yieldEstimator;
     /**
      * 오퍼레이션 명세(선택) — 작업 종류(`FlowTask.kind` = `OperationDef.key`) → 소요·변동·모수.
      * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
@@ -1245,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;
     }
     /**
@@ -1725,6 +1728,23 @@ export class FlowEngine {
             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).
      *
@@ -1745,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]]) });
     }
     /**
      * 시뮬 명세 자기보고 — **어디까지 데이터로 말했고 어디부터 우리가 코드에 고정한 상수인가.**
@@ -1769,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 {
@@ -2008,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/index.d.ts

@@ -30,6 +30,8 @@ export { YmsKernel } from './yms-kernel.ts';
 export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from './mes-kernel.ts';
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from './ems-kernel.ts';
 export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord } from './energy-ingest.ts';
+export { ingestOperationalRecords, isOperationalRecord, operationalKindOf } from './operational-ingest.ts';
+export type { OperationalKind, OperationalRecord, OperationalIngestOptions } from './operational-ingest.ts';
 export { attributeEnergy, electricityCost, energyIntensity, energyOfWindows } from './energy-attribution.ts';
 export type { AttributionBasis, AttributionResult, ElectricityCost, EnergyConsumer, EnergyPool, EnergyShare, IntensityInput, IntensityResult, IntensityDenominator, TariffDeclaration, WeightKind, WindowedEnergy } from './energy-attribution.ts';
 export type { EnergyRecord, EnergyEquipmentRecord, EnergyIngestOptions, EnergyIngestResult } from './energy-ingest.ts';

package/dist/index.js

@@ -30,6 +30,8 @@ export { YmsKernel } from "./yms-kernel.js";
 export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from "./mes-kernel.js";
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from "./ems-kernel.js";
 export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord } from "./energy-ingest.js";
+/* 운영 사실의 문 — 리듀서가 접는 여섯이 들어오는 자리(미러가 시뮬보다 가난하지 않게). */
+export { ingestOperationalRecords, isOperationalRecord, operationalKindOf } from "./operational-ingest.js";
 export { attributeEnergy, electricityCost, energyIntensity, energyOfWindows } from "./energy-attribution.js";
 /* 에너지 상태 타입은 **계약**에 있다(상태의 모양은 계약이다) — contract 의 `export *` 가 이미 낸다. */
 export * from "./vocabulary.js";

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/operational-ingest.d.ts

@@ -0,0 +1,44 @@
+import type { IngestResult } from './face2-adapter.ts';
+/** 이 문이 받는 여섯 가지 — 리듀서가 접는 것과 같은 목록(주목 확인은 우리 안의 행위라 제외). */
+export type OperationalKind = 'task' | 'equipment' | 'person' | 'asset' | 'order' | 'quality';
+/**
+ * 정규 운영 레코드 — **델타의 필드 이름 + 시각(`at`)**.
+ *
+ * `at` 은 봉투의 `eventTime` 이 된다(리듀서가 늦게 온 옛 사실을 걸러내는 기준). 페이로드에는 싣지
+ * 않는다 — 델타에 없는 필드이고, 같은 사실이 두 시각을 갖지 않게.
+ */
+export interface OperationalRecordEnvelopeFields {
+    /** 발생 시각(ISO) — 없으면 `defaultEventTime`, 그것도 없으면 거부한다. */
+    at?: string;
+    /** 기록 시각(ISO) — 같은 발생 시각이 겹칠 때의 보조 순서. 리듀서가 페이로드에서 읽는다. */
+    recordTime?: string;
+}
+export type OperationalRecord = Record<string, unknown> & OperationalRecordEnvelopeFields;
+export interface OperationalIngestOptions {
+    tenantId: string;
+    /** 레코드에 시각이 없을 때 쓸 값 — 주지 않으면 그 레코드를 거부한다. */
+    defaultEventTime?: string;
+}
+/**
+ * 이 레코드가 어느 운영 사실인가 — **라우팅 판정을 한 곳에 둔다**(소비처가 각자 짐작하지 않게).
+ *
+ * EPCIS·에너지와 겹치지 않게 본다: `epc`·`meterId` 가 있으면 그쪽 어휘이고, `equipmentId` 는 설비
+ * **에너지** 상태의 이름이다(운영 설비는 `moverId`). 품질은 설비와 정체 필드를 공유하므로 `good` 으로
+ * 가른다 — 둘 다 아니면 어느 쪽인지 모르는 것이고, 모르면 받지 않는다.
+ *
+ * ── 순서가 뜻을 갖는다: **주체와 참조는 다르다** ────────────────────────────
+ * 정체 필드는 하나만 오지 않는다. 설비·사람·자산 델타는 「지금 붙어 있는 작업」(`taskId`)을 함께 싣고,
+ * 작업 델타는 「소속 오더」(`orderId`)를 함께 싣는다. 그래서 아무 정체 필드나 먼저 보면 **참조를 주체로
+ * 읽는다** — 실제로 그랬다: `moverId` + `taskId` 인 설비 사실을 작업으로 읽어 「계약에 없는 필드」로
+ * 거부했다. 자원(설비·사람·자산)을 먼저 보고, 작업을 오더보다 먼저 본다.
+ */
+export declare function operationalKindOf(record: unknown): OperationalKind | undefined;
+/** 이 레코드가 운영 사실인가 — 호스트의 라우팅이 묻는 자리. */
+export declare function isOperationalRecord(record: unknown): boolean;
+/**
+ * 운영 레코드들을 봉투로 — 유효한 것만 통과하고 나머지는 **이유와 함께** 남는다.
+ *
+ * 봉투는 다른 어휘와 같은 것을 쓴다(`CanonicalEnvelope`) — 그래서 저널·리플레이·시간여행·성과 폴드를
+ * 그대로 얻는다. 어휘만 자기 것이다.
+ */
+export declare function ingestOperationalRecords(records: OperationalRecord | OperationalRecord[] | undefined | null, opts: OperationalIngestOptions): IngestResult;

package/dist/operational-ingest.js

@@ -0,0 +1,283 @@
+/*
+ * 운영 사실 인제스트 — **작업·설비·사람·자산·오더·품질이 들어오는 문.** (ADR-0029 어휘 넓히기)
+ *
+ * ── 무엇이 없었나 (2026-08-19) ──────────────────────────────────────────────
+ * 관측 리듀서는 이 여섯을 **이미 접는다**(`observed-reducer.ts` 의 `OP_EVENT.*` 분기). 그런데 라이브
+ * 인제스트 문은 어휘를 셋만 알았다: EPCIS 품목 사실, 에너지 계량, 설비 에너지 상태. 그래서 원본이
+ * 「이 작업이 끝났다」·「이 설비가 고장이다」를 말할 **길이 없었다** — 넣으면 `epc` 가 없어 EPCIS
+ * 검증에서 거부됐다.
+ *
+ * 그 결과가 이 프로젝트가 가장 싫어하는 모양이었다: **시뮬만 아는 상태.** 시뮬 커널은 작업과 설비를
+ * 알고 미러는 영원히 몰랐다. 그러면 같은 화면이 두 구동에서 다른 것을 말하고, 미러 위에 세운 예측은
+ * 「진행 중인 일이 하나도 없는 현장」에서 출발한다.
+ *
+ * ── 어휘는 델타의 이름이다 ──────────────────────────────────────────────────
+ * 필드 이름을 새로 짓지 않는다. `TaskStatusDelta`·`EquipmentStatusDelta`… 가 이미 계약이고, 리듀서가
+ * 그 이름으로 읽는다. 여기서 다른 이름을 받아 옮기면 **같은 사실에 두 어휘**가 생긴다(에너지가 그
+ * 규율을 먼저 세웠다: "필드 이름이 계약이다").
+ *
+ * ── 무엇을 거부하나 ─────────────────────────────────────────────────────────
+ * 지어낼 수 없는 것이 빠지면 거부한다 — 정체(누구의 상태인가)와 상태다. 그리고 **접을 수 없는 낱말**도
+ * 거부한다: 설비 상태를 `'RUNNING'` 으로 받으면 아무 오류 없이 가동률이 0% 가 되고(누적기는 `busy`·
+ * `down` 만 센다), 사람이 `'available'` 이면 배정에서 조용히 사라진다. 그 실패는 화면에서 「일이 없는
+ * 공장」으로 보이고 원인을 되짚을 수 없다. 그래서 커널이 접을 수 있는 낱말만 받고, **받는 낱말을 이유에
+ * 적어** 커넥터가 매핑을 고칠 수 있게 한다(매핑=밖, 검증=커널).
+ *
+ * 오더의 상태·종류는 **열려 있다** — 도메인이 소유한다(`picking`·`packed`·`shipped`…). 커널이 그 낱말로
+ * 무엇을 접지 않으므로 닫을 근거가 없다.
+ *
+ * ── 파생은 받아도 커널이 다시 계산한다 ──────────────────────────────────────
+ * 작업의 진척(`progress`)은 계약에 있어 받지만, 상태에 앉는 값은 커널이 **소요·남은 시간에서 다시
+ * 계산한 것**이다(`progressOf`). 그러니 원본이 진척을 보이게 하려면 `durationMs`·`remainingMs` 를 보내야
+ * 한다 — 파생을 사실로 삼지 않는 규율이고, 이 문을 붙이는 사람이 알아야 하는 사실이라 여기 적는다.
+ *
+ * 모르는 필드는 **조용히 버리지 않고 거부한다.** `taskID` 처럼 한 글자 틀린 이름은 통과시키면 영원히
+ * 보이지 않는 손실이 된다(이 문에는 아직 옛 발신자가 없어 호환 부담도 없다).
+ */
+import { OP_EVENT } from "./contract.js";
+/**
+ * 닫아 둔 낱말과 그 이유.
+ *  · 작업 상태 — 성과 폴드가 `completed`·`in-progress` 로 갈린다(`kpi-fold`).
+ *  · 설비 상태 — OEE 누적기가 `busy`·`down` 만 센다. 그 밖의 낱말은 가동률 0% 로 조용히 앉는다.
+ *  · 사람·자산 상태 — 배정이 `idle` 을 찾는다. 다른 낱말이면 있는 자원이 없는 것이 된다.
+ */
+const TASK_STATUS = ['created', 'assigned', 'in-progress', 'completed'];
+const EQUIPMENT_STATUS = ['idle', 'busy', 'down'];
+const PERSON_STATUS = ['idle', 'busy'];
+const ASSET_STATUS = ['idle', 'in-use'];
+const SPECS = {
+    task: {
+        eventType: OP_EVENT.task,
+        identity: 'taskId',
+        /* 종류가 없으면 성과를 종류별로 접을 수 없고(선언된 시간·수율이 종류로 붙는다) 지어낼 수도 없다. */
+        required: ['taskId', 'kind', 'status'],
+        fields: {
+            taskId: 'string', kind: 'string', status: 'string', fromNode: 'string', toNode: 'string',
+            itemRefs: 'string[]', resourceRef: 'string', resources: 'string[]', personnel: 'string[]', assets: 'string[]',
+            orderId: 'string', intent: 'string', progress: 'number', remainingMs: 'number', durationMs: 'number',
+            startedAtSimMs: 'number', outcome: 'string', priority: 'number', startTime: 'string', endTime: 'string',
+            materialActual: 'object[]', recordTime: 'string'
+        },
+        enums: {
+            status: TASK_STATUS,
+            intent: ['transport', 'process', 'dwell'],
+            /* 품질 판정은 **있었던 작업만** — 없음은 「양품」이 아니라 「판정하지 않았다」다. */
+            outcome: ['good', 'scrap']
+        }
+    },
+    equipment: {
+        eventType: OP_EVENT.equipment,
+        identity: 'moverId', // vocabulary-guard: allow 저널 와이어 필드(델타의 이름이 계약이다)
+        required: ['moverId', 'kind', 'status'], // vocabulary-guard: allow 위와 같은 이유
+        fields: {
+            moverId: 'string', kind: 'string', status: 'string', location: 'string', homeLocation: 'string', // vocabulary-guard: allow
+            taskId: 'string', held: 'boolean', effectiveStart: 'string', effectiveEnd: 'string', recordTime: 'string',
+            /* 이동 구간 — 실 시스템도 줄 수 있는 사실이다(AGV·RTLS 가 출발·도착·소요를 낸다). 안쪽 필드까지
+               재검사하지는 않는다: 그 모양은 `EquipmentMotion` 계약이고, 여기서 두 번 지키면 두 벌이 된다. */
+            motion: 'object'
+        },
+        enums: { status: EQUIPMENT_STATUS }
+    },
+    person: {
+        eventType: OP_EVENT.person,
+        identity: 'personId',
+        required: ['personId', 'status'],
+        fields: {
+            personId: 'string', status: 'string', personnelClassIds: 'string[]', taskId: 'string', location: 'string',
+            offShift: 'boolean', effectiveStart: 'string', effectiveEnd: 'string', recordTime: 'string'
+        },
+        enums: { status: PERSON_STATUS }
+    },
+    asset: {
+        eventType: OP_EVENT.asset,
+        identity: 'assetId',
+        required: ['assetId', 'status'],
+        fields: {
+            assetId: 'string', status: 'string', assetClassIds: 'string[]', location: 'string', taskId: 'string',
+            carrying: 'string', effectiveStart: 'string', effectiveEnd: 'string', recordTime: 'string'
+        },
+        enums: { status: ASSET_STATUS }
+    },
+    order: {
+        eventType: OP_EVENT.order,
+        identity: 'orderId',
+        /*
+         * 요청량·이행량을 **함께** 받는다. 없으면 리듀서가 진척을 0 으로 적는데(`requested ? … : 0`),
+         * 그것은 「모른다」가 아니라 「아무것도 안 됐다」로 읽힌다 — 결측을 0 으로 메우지 않는다.
+         */
+        required: ['orderId', 'kind', 'status', 'requested', 'fulfilled'],
+        fields: {
+            orderId: 'string', kind: 'string', status: 'string', requested: 'number', fulfilled: 'number',
+            gtin: 'string', held: 'boolean', lines: 'object[]', priority: 'number', startTime: 'string', endTime: 'string',
+            allocated: 'string[]', bizTransaction: 'string', dockDoor: 'string', windowStartMs: 'number', recordTime: 'string'
+        }
+        /* 상태·종류는 도메인이 소유한다 — 닫지 않는다. */
+    },
+    quality: {
+        eventType: OP_EVENT.quality,
+        identity: 'moverId', // vocabulary-guard: allow 저널 와이어 필드
+        /* 누적 카운터가 없으면 OEE 가 양품률을 못 센다 — 판정 하나만으로는 비율이 나오지 않는다. */
+        required: ['moverId', 'good', 'goodCount', 'scrapCount'], // vocabulary-guard: allow
+        fields: { moverId: 'string', good: 'boolean', goodCount: 'number', scrapCount: 'number', recordTime: 'string' } // vocabulary-guard: allow
+    }
+};
+/**
+ * 이 레코드가 어느 운영 사실인가 — **라우팅 판정을 한 곳에 둔다**(소비처가 각자 짐작하지 않게).
+ *
+ * EPCIS·에너지와 겹치지 않게 본다: `epc`·`meterId` 가 있으면 그쪽 어휘이고, `equipmentId` 는 설비
+ * **에너지** 상태의 이름이다(운영 설비는 `moverId`). 품질은 설비와 정체 필드를 공유하므로 `good` 으로
+ * 가른다 — 둘 다 아니면 어느 쪽인지 모르는 것이고, 모르면 받지 않는다.
+ *
+ * ── 순서가 뜻을 갖는다: **주체와 참조는 다르다** ────────────────────────────
+ * 정체 필드는 하나만 오지 않는다. 설비·사람·자산 델타는 「지금 붙어 있는 작업」(`taskId`)을 함께 싣고,
+ * 작업 델타는 「소속 오더」(`orderId`)를 함께 싣는다. 그래서 아무 정체 필드나 먼저 보면 **참조를 주체로
+ * 읽는다** — 실제로 그랬다: `moverId` + `taskId` 인 설비 사실을 작업으로 읽어 「계약에 없는 필드」로
+ * 거부했다. 자원(설비·사람·자산)을 먼저 보고, 작업을 오더보다 먼저 본다.
+ */
+export function operationalKindOf(record) {
+    if (!record || typeof record !== 'object')
+        return undefined;
+    const r = record;
+    if (r.epc !== undefined || r.meterId !== undefined || r.equipmentId !== undefined)
+        return undefined;
+    const has = (k) => typeof r[k] === 'string' && r[k].trim().length > 0;
+    /* vocabulary-guard: allow 저널 와이어 필드로 가른다 */
+    if (has('moverId'))
+        return r.good !== undefined ? 'quality' : 'equipment';
+    if (has('personId'))
+        return 'person';
+    if (has('assetId'))
+        return 'asset';
+    if (has('taskId'))
+        return 'task'; // 작업이 든 `orderId` 는 소속(참조)이다
+    if (has('orderId'))
+        return 'order';
+    return undefined;
+}
+/** 이 레코드가 운영 사실인가 — 호스트의 라우팅이 묻는 자리. */
+export function isOperationalRecord(record) {
+    return operationalKindOf(record) !== undefined;
+}
+/**
+ * 운영 레코드들을 봉투로 — 유효한 것만 통과하고 나머지는 **이유와 함께** 남는다.
+ *
+ * 봉투는 다른 어휘와 같은 것을 쓴다(`CanonicalEnvelope`) — 그래서 저널·리플레이·시간여행·성과 폴드를
+ * 그대로 얻는다. 어휘만 자기 것이다.
+ */
+export function ingestOperationalRecords(records, opts) {
+    const arr = Array.isArray(records) ? records : records ? [records] : [];
+    const accepted = [];
+    const rejected = [];
+    let seq = 0;
+    for (const record of arr) {
+        const kind = operationalKindOf(record);
+        if (!kind) {
+            rejected.push({
+                record,
+                errors: ['어느 운영 사실인지 모른다 — 정체 필드가 필요하다(taskId · moverId(+good=품질) · personId · assetId · orderId)'] // vocabulary-guard: allow 거부 이유가 계약 필드 이름을 말한다
+            });
+            continue;
+        }
+        const spec = SPECS[kind];
+        const r = record;
+        const errors = [];
+        /* 모르는 이름은 거부한다 — 한 글자 틀린 필드가 조용히 사라지는 것을 막는다. */
+        const unknown = Object.keys(r).filter(k => k !== 'at' && spec.fields[k] === undefined);
+        if (unknown.length)
+            errors.push(`${kind}: 계약에 없는 필드 — ${unknown.join(', ')}`);
+        for (const name of spec.required) {
+            const v = r[name];
+            if (v === undefined || v === null || v === '')
+                errors.push(`${kind}: ${name} 없음 — 지어낼 수 없는 값이다`);
+        }
+        const data = {};
+        for (const [name, type] of Object.entries(spec.fields)) {
+            const v = r[name];
+            if (v === undefined || v === null || v === '')
+                continue;
+            switch (type) {
+                case 'string': {
+                    if (typeof v !== 'string') {
+                        errors.push(`${kind}.${name} 이 문자열이 아니다: ${JSON.stringify(v)}`);
+                        break;
+                    }
+                    const allowed = spec.enums?.[name];
+                    if (allowed && !allowed.includes(v)) {
+                        errors.push(`${kind}.${name} 이 커널이 접는 낱말이 아니다: ${JSON.stringify(v)} — 받는 값은 ${allowed.join(' · ')}`);
+                        break;
+                    }
+                    data[name] = v;
+                    break;
+                }
+                case 'number': {
+                    const n = Number(v);
+                    if (typeof v === 'boolean' || !Number.isFinite(n)) {
+                        errors.push(`${kind}.${name} 가 수가 아니다: ${JSON.stringify(v)}`);
+                        break;
+                    }
+                    /* 진척은 비율이다 — 백분율(95)을 그대로 받으면 화면이 9,500% 를 말한다. */
+                    if (name === 'progress' && (n < 0 || n > 1)) {
+                        errors.push(`${kind}.progress 는 0~1 비율이다: ${n}`);
+                        break;
+                    }
+                    if ((name === 'requested' || name === 'fulfilled' || name === 'goodCount' || name === 'scrapCount') && n < 0) {
+                        errors.push(`${kind}.${name} 가 음수다: ${n}`);
+                        break;
+                    }
+                    data[name] = n;
+                    break;
+                }
+                case 'boolean': {
+                    if (typeof v !== 'boolean') {
+                        errors.push(`${kind}.${name} 가 참/거짓이 아니다: ${JSON.stringify(v)}`);
+                        break;
+                    }
+                    data[name] = v;
+                    break;
+                }
+                case 'string[]': {
+                    if (!Array.isArray(v) || v.some(x => typeof x !== 'string')) {
+                        errors.push(`${kind}.${name} 가 문자열 배열이 아니다: ${JSON.stringify(v)}`);
+                        break;
+                    }
+                    data[name] = v.slice();
+                    break;
+                }
+                case 'object': {
+                    if (Array.isArray(v) || typeof v !== 'object') {
+                        errors.push(`${kind}.${name} 가 객체가 아니다: ${JSON.stringify(v)}`);
+                        break;
+                    }
+                    data[name] = { ...v };
+                    break;
+                }
+                case 'object[]': {
+                    if (!Array.isArray(v) || v.some(x => !x || typeof x !== 'object')) {
+                        errors.push(`${kind}.${name} 가 객체 배열이 아니다: ${JSON.stringify(v)}`);
+                        break;
+                    }
+                    data[name] = v.map(x => ({ ...x }));
+                    break;
+                }
+            }
+        }
+        const at = String(r.at ?? '').trim() || opts.defaultEventTime;
+        const atMs = at ? Date.parse(at) : Number.NaN;
+        if (!Number.isFinite(atMs)) {
+            /* 시각이 없으면 순서를 판정할 수 없다 — 늦게 온 옛 사실이 최신 상태를 덮어써 위치가 과거로 튄다. */
+            errors.push(`${kind}: at 없음/형식 오류 — 시각 없이는 늦게 온 옛 사실을 걸러낼 수 없다`);
+        }
+        if (errors.length) {
+            rejected.push({ record, errors });
+            continue;
+        }
+        accepted.push({
+            eventId: `${opts.tenantId}-op-${kind}-${++seq}`,
+            eventType: spec.eventType,
+            eventTime: new Date(atMs).toISOString(),
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}

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/vocabulary.d.ts

@@ -1,5 +1,14 @@
-/** 금지 어휘 — 표준 어휘로 대체된 옛 낱말. 파생 식별자까지 잡도록 부분 일치로 본다. */
-export declare const RETIRED_VOCABULARY: readonly ["mover", "Mover", "MOVER", "node", "Node", "NODE"];
+/**
+ * 금지 어휘 — 표준 어휘로 대체된 옛 낱말. 파생 식별자까지 잡도록 부분 일치로 본다.
+ *
+ * `BoardDef`·`loadBoard` 는 ADR-0033 으로 `TwinModelDef`·`loadTwinModel` 이 됐다. 커널 소스에는
+ * **0곳**이라 개명이 끝났는데, 문서에는 31곳이 남아 있었다(2026-08-19 실측) — 코드에 없는 이름으로
+ * 설계를 설명하고 있었다. 코드에 0곳이므로 여기 올려 되돌아오는 것을 막는다.
+ *
+ * (문서 쪽은 `test/doc-vocabulary-guard.test.ts` 가 **자기 목록**으로 본다 — 이 목록의 `node`·`mover` 는
+ *  ADR 기록이 없어 문서의 개념 명사에까지 들이대지 않는다.)
+ */
+export declare const RETIRED_VOCABULARY: readonly ["mover", "Mover", "MOVER", "node", "Node", "NODE", "BoardDef", "loadBoard"];
 /**
  * 예외 — 남아 있는 것이 **정당한** 토큰. 각 항목에 이유가 붙는다.
  *

package/dist/vocabulary.js

@@ -10,8 +10,17 @@
  *
  * 예외는 **이유와 함께** 여기 적는다. 주석에만 적으면 다음 사람이 "원래 그런가 보다" 하고 넘긴다.
  */
-/** 금지 어휘 — 표준 어휘로 대체된 옛 낱말. 파생 식별자까지 잡도록 부분 일치로 본다. */
-export const RETIRED_VOCABULARY = ['mover', 'Mover', 'MOVER', 'node', 'Node', 'NODE'];
+/**
+ * 금지 어휘 — 표준 어휘로 대체된 옛 낱말. 파생 식별자까지 잡도록 부분 일치로 본다.
+ *
+ * `BoardDef`·`loadBoard` 는 ADR-0033 으로 `TwinModelDef`·`loadTwinModel` 이 됐다. 커널 소스에는
+ * **0곳**이라 개명이 끝났는데, 문서에는 31곳이 남아 있었다(2026-08-19 실측) — 코드에 없는 이름으로
+ * 설계를 설명하고 있었다. 코드에 0곳이므로 여기 올려 되돌아오는 것을 막는다.
+ *
+ * (문서 쪽은 `test/doc-vocabulary-guard.test.ts` 가 **자기 목록**으로 본다 — 이 목록의 `node`·`mover` 는
+ *  ADR 기록이 없어 문서의 개념 명사에까지 들이대지 않는다.)
+ */
+export const RETIRED_VOCABULARY = ['mover', 'Mover', 'MOVER', 'node', 'Node', 'NODE', 'BoardDef', 'loadBoard'];
 /**
  * 예외 — 남아 있는 것이 **정당한** 토큰. 각 항목에 이유가 붙는다.
  *

package/dist-cjs/index.cjs

@@ -117,10 +117,12 @@ __export(index_exports, {
   ingest: () => ingest,
   ingestEnergyEquipmentRecords: () => ingestEnergyEquipmentRecords,
   ingestEnergyRecords: () => ingestEnergyRecords,
+  ingestOperationalRecords: () => ingestOperationalRecords,
   isElectricalLocationType: () => isElectricalLocationType,
   isEnergyEquipmentRecord: () => isEnergyEquipmentRecord,
   isEnergyRecord: () => isEnergyRecord,
   isEquipmentLevel: () => isEquipmentLevel,
+  isOperationalRecord: () => isOperationalRecord,
   isoDurationHours: () => isoDurationHours,
   itemKeyOf: () => itemKeyOf,
   levelOfLocationType: () => levelOfLocationType,
@@ -134,6 +136,7 @@ __export(index_exports, {
   objectEvent: () => objectEvent,
   offCalendarAt: () => offCalendarAt,
   offCalendarReasonAt: () => offCalendarReasonAt,
+  operationalKindOf: () => operationalKindOf,
   operationsCapabilityOf: () => operationsCapabilityOf,
   parseEpc: () => parseEpc,
   parseIsoDuration: () => parseIsoDuration,
@@ -2630,6 +2633,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;
@@ -3172,6 +3176,13 @@ var FlowEngine = class {
   policy;
   /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
   durationEstimator;
+  /**
+   * 양품률 시임(선택) — **이력에서 배운 수율.** 소요시간과 같은 자리·같은 규율이다 (2026-08-19).
+   *
+   * 없으면 선언값(현장→원천), 그것도 없으면 도메인 상수. 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
+   * 주입은 호스트가 한다(저널을 접는 쪽이 이력을 안다) — 커널은 시임만 든다.
+   */
+  yieldEstimator;
   /**
    * 오퍼레이션 명세(선택) — 작업 종류(`FlowTask.kind` = `OperationDef.key`) → 소요·변동·모수.
    * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
@@ -4003,7 +4014,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;
   }
   /**
@@ -4437,6 +4453,23 @@ var FlowEngine = class {
     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).
    *
@@ -4455,12 +4488,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]]) });
   }
   /**
    * 시뮬 명세 자기보고 — **어디까지 데이터로 말했고 어디부터 우리가 코드에 고정한 상수인가.**
@@ -4476,7 +4519,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 {
@@ -4701,6 +4746,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 } : {},
@@ -6163,7 +6210,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);
@@ -6275,7 +6323,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);
@@ -7120,6 +7169,273 @@ function ingestEnergyEquipmentRecords(records, opts) {
   return { accepted, rejected };
 }
 
+// src/operational-ingest.ts
+var TASK_STATUS = ["created", "assigned", "in-progress", "completed"];
+var EQUIPMENT_STATUS = ["idle", "busy", "down"];
+var PERSON_STATUS = ["idle", "busy"];
+var ASSET_STATUS = ["idle", "in-use"];
+var SPECS = {
+  task: {
+    eventType: OP_EVENT.task,
+    identity: "taskId",
+    /* 종류가 없으면 성과를 종류별로 접을 수 없고(선언된 시간·수율이 종류로 붙는다) 지어낼 수도 없다. */
+    required: ["taskId", "kind", "status"],
+    fields: {
+      taskId: "string",
+      kind: "string",
+      status: "string",
+      fromNode: "string",
+      toNode: "string",
+      itemRefs: "string[]",
+      resourceRef: "string",
+      resources: "string[]",
+      personnel: "string[]",
+      assets: "string[]",
+      orderId: "string",
+      intent: "string",
+      progress: "number",
+      remainingMs: "number",
+      durationMs: "number",
+      startedAtSimMs: "number",
+      outcome: "string",
+      priority: "number",
+      startTime: "string",
+      endTime: "string",
+      materialActual: "object[]",
+      recordTime: "string"
+    },
+    enums: {
+      status: TASK_STATUS,
+      intent: ["transport", "process", "dwell"],
+      /* 품질 판정은 **있었던 작업만** — 없음은 「양품」이 아니라 「판정하지 않았다」다. */
+      outcome: ["good", "scrap"]
+    }
+  },
+  equipment: {
+    eventType: OP_EVENT.equipment,
+    identity: "moverId",
+    // vocabulary-guard: allow 저널 와이어 필드(델타의 이름이 계약이다)
+    required: ["moverId", "kind", "status"],
+    // vocabulary-guard: allow 위와 같은 이유
+    fields: {
+      moverId: "string",
+      kind: "string",
+      status: "string",
+      location: "string",
+      homeLocation: "string",
+      // vocabulary-guard: allow
+      taskId: "string",
+      held: "boolean",
+      effectiveStart: "string",
+      effectiveEnd: "string",
+      recordTime: "string",
+      /* 이동 구간 — 실 시스템도 줄 수 있는 사실이다(AGV·RTLS 가 출발·도착·소요를 낸다). 안쪽 필드까지
+         재검사하지는 않는다: 그 모양은 `EquipmentMotion` 계약이고, 여기서 두 번 지키면 두 벌이 된다. */
+      motion: "object"
+    },
+    enums: { status: EQUIPMENT_STATUS }
+  },
+  person: {
+    eventType: OP_EVENT.person,
+    identity: "personId",
+    required: ["personId", "status"],
+    fields: {
+      personId: "string",
+      status: "string",
+      personnelClassIds: "string[]",
+      taskId: "string",
+      location: "string",
+      offShift: "boolean",
+      effectiveStart: "string",
+      effectiveEnd: "string",
+      recordTime: "string"
+    },
+    enums: { status: PERSON_STATUS }
+  },
+  asset: {
+    eventType: OP_EVENT.asset,
+    identity: "assetId",
+    required: ["assetId", "status"],
+    fields: {
+      assetId: "string",
+      status: "string",
+      assetClassIds: "string[]",
+      location: "string",
+      taskId: "string",
+      carrying: "string",
+      effectiveStart: "string",
+      effectiveEnd: "string",
+      recordTime: "string"
+    },
+    enums: { status: ASSET_STATUS }
+  },
+  order: {
+    eventType: OP_EVENT.order,
+    identity: "orderId",
+    /*
+     * 요청량·이행량을 **함께** 받는다. 없으면 리듀서가 진척을 0 으로 적는데(`requested ? … : 0`),
+     * 그것은 「모른다」가 아니라 「아무것도 안 됐다」로 읽힌다 — 결측을 0 으로 메우지 않는다.
+     */
+    required: ["orderId", "kind", "status", "requested", "fulfilled"],
+    fields: {
+      orderId: "string",
+      kind: "string",
+      status: "string",
+      requested: "number",
+      fulfilled: "number",
+      gtin: "string",
+      held: "boolean",
+      lines: "object[]",
+      priority: "number",
+      startTime: "string",
+      endTime: "string",
+      allocated: "string[]",
+      bizTransaction: "string",
+      dockDoor: "string",
+      windowStartMs: "number",
+      recordTime: "string"
+    }
+    /* 상태·종류는 도메인이 소유한다 — 닫지 않는다. */
+  },
+  quality: {
+    eventType: OP_EVENT.quality,
+    identity: "moverId",
+    // vocabulary-guard: allow 저널 와이어 필드
+    /* 누적 카운터가 없으면 OEE 가 양품률을 못 센다 — 판정 하나만으로는 비율이 나오지 않는다. */
+    required: ["moverId", "good", "goodCount", "scrapCount"],
+    // vocabulary-guard: allow
+    fields: { moverId: "string", good: "boolean", goodCount: "number", scrapCount: "number", recordTime: "string" }
+    // vocabulary-guard: allow
+  }
+};
+function operationalKindOf(record) {
+  if (!record || typeof record !== "object") return void 0;
+  const r = record;
+  if (r.epc !== void 0 || r.meterId !== void 0 || r.equipmentId !== void 0) return void 0;
+  const has = (k) => typeof r[k] === "string" && r[k].trim().length > 0;
+  if (has("moverId")) return r.good !== void 0 ? "quality" : "equipment";
+  if (has("personId")) return "person";
+  if (has("assetId")) return "asset";
+  if (has("taskId")) return "task";
+  if (has("orderId")) return "order";
+  return void 0;
+}
+function isOperationalRecord(record) {
+  return operationalKindOf(record) !== void 0;
+}
+function ingestOperationalRecords(records, opts) {
+  const arr = Array.isArray(records) ? records : records ? [records] : [];
+  const accepted = [];
+  const rejected = [];
+  let seq = 0;
+  for (const record of arr) {
+    const kind = operationalKindOf(record);
+    if (!kind) {
+      rejected.push({
+        record,
+        errors: ["\uC5B4\uB290 \uC6B4\uC601 \uC0AC\uC2E4\uC778\uC9C0 \uBAA8\uB978\uB2E4 \u2014 \uC815\uCCB4 \uD544\uB4DC\uAC00 \uD544\uC694\uD558\uB2E4(taskId \xB7 moverId(+good=\uD488\uC9C8) \xB7 personId \xB7 assetId \xB7 orderId)"]
+        // vocabulary-guard: allow 거부 이유가 계약 필드 이름을 말한다
+      });
+      continue;
+    }
+    const spec = SPECS[kind];
+    const r = record;
+    const errors = [];
+    const unknown = Object.keys(r).filter((k) => k !== "at" && spec.fields[k] === void 0);
+    if (unknown.length) errors.push(`${kind}: \uACC4\uC57D\uC5D0 \uC5C6\uB294 \uD544\uB4DC \u2014 ${unknown.join(", ")}`);
+    for (const name of spec.required) {
+      const v = r[name];
+      if (v === void 0 || v === null || v === "") errors.push(`${kind}: ${name} \uC5C6\uC74C \u2014 \uC9C0\uC5B4\uB0BC \uC218 \uC5C6\uB294 \uAC12\uC774\uB2E4`);
+    }
+    const data = {};
+    for (const [name, type] of Object.entries(spec.fields)) {
+      const v = r[name];
+      if (v === void 0 || v === null || v === "") continue;
+      switch (type) {
+        case "string": {
+          if (typeof v !== "string") {
+            errors.push(`${kind}.${name} \uC774 \uBB38\uC790\uC5F4\uC774 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+            break;
+          }
+          const allowed = spec.enums?.[name];
+          if (allowed && !allowed.includes(v)) {
+            errors.push(`${kind}.${name} \uC774 \uCEE4\uB110\uC774 \uC811\uB294 \uB0B1\uB9D0\uC774 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)} \u2014 \uBC1B\uB294 \uAC12\uC740 ${allowed.join(" \xB7 ")}`);
+            break;
+          }
+          data[name] = v;
+          break;
+        }
+        case "number": {
+          const n = Number(v);
+          if (typeof v === "boolean" || !Number.isFinite(n)) {
+            errors.push(`${kind}.${name} \uAC00 \uC218\uAC00 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+            break;
+          }
+          if (name === "progress" && (n < 0 || n > 1)) {
+            errors.push(`${kind}.progress \uB294 0~1 \uBE44\uC728\uC774\uB2E4: ${n}`);
+            break;
+          }
+          if ((name === "requested" || name === "fulfilled" || name === "goodCount" || name === "scrapCount") && n < 0) {
+            errors.push(`${kind}.${name} \uAC00 \uC74C\uC218\uB2E4: ${n}`);
+            break;
+          }
+          data[name] = n;
+          break;
+        }
+        case "boolean": {
+          if (typeof v !== "boolean") {
+            errors.push(`${kind}.${name} \uAC00 \uCC38/\uAC70\uC9D3\uC774 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+            break;
+          }
+          data[name] = v;
+          break;
+        }
+        case "string[]": {
+          if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+            errors.push(`${kind}.${name} \uAC00 \uBB38\uC790\uC5F4 \uBC30\uC5F4\uC774 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+            break;
+          }
+          data[name] = v.slice();
+          break;
+        }
+        case "object": {
+          if (Array.isArray(v) || typeof v !== "object") {
+            errors.push(`${kind}.${name} \uAC00 \uAC1D\uCCB4\uAC00 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+            break;
+          }
+          data[name] = { ...v };
+          break;
+        }
+        case "object[]": {
+          if (!Array.isArray(v) || v.some((x) => !x || typeof x !== "object")) {
+            errors.push(`${kind}.${name} \uAC00 \uAC1D\uCCB4 \uBC30\uC5F4\uC774 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+            break;
+          }
+          data[name] = v.map((x) => ({ ...x }));
+          break;
+        }
+      }
+    }
+    const at = String(r.at ?? "").trim() || opts.defaultEventTime;
+    const atMs = at ? Date.parse(at) : Number.NaN;
+    if (!Number.isFinite(atMs)) {
+      errors.push(`${kind}: at \uC5C6\uC74C/\uD615\uC2DD \uC624\uB958 \u2014 \uC2DC\uAC01 \uC5C6\uC774\uB294 \uB2A6\uAC8C \uC628 \uC61B \uC0AC\uC2E4\uC744 \uAC78\uB7EC\uB0BC \uC218 \uC5C6\uB2E4`);
+    }
+    if (errors.length) {
+      rejected.push({ record, errors });
+      continue;
+    }
+    accepted.push({
+      eventId: `${opts.tenantId}-op-${kind}-${++seq}`,
+      eventType: spec.eventType,
+      eventTime: new Date(atMs).toISOString(),
+      tenantId: opts.tenantId,
+      data
+    });
+  }
+  return { accepted, rejected };
+}
+
 // src/energy-attribution.ts
 var near = (a, b, eps = 1e-9) => Math.abs(a - b) <= eps;
 function attributeEnergy(opts) {
@@ -7304,7 +7620,7 @@ function electricityCost(input) {
 }
 
 // src/vocabulary.ts
-var RETIRED_VOCABULARY = ["mover", "Mover", "MOVER", "node", "Node", "NODE"];
+var RETIRED_VOCABULARY = ["mover", "Mover", "MOVER", "node", "Node", "NODE", "BoardDef", "loadBoard"];
 var VOCABULARY_EXCEPTIONS = [
   /* ── 저널 와이어 필드 — append-only 역사이므로 이름을 바꾸지 않는다 ───────
    * 같은 사실이 시점에 따라 다른 키로 들어가면 낡은 이름보다 나쁘다. 개명은 이벤트 스키마
@@ -7445,10 +7761,12 @@ function retiredVocabularyIn(line) {
   ingest,
   ingestEnergyEquipmentRecords,
   ingestEnergyRecords,
+  ingestOperationalRecords,
   isElectricalLocationType,
   isEnergyEquipmentRecord,
   isEnergyRecord,
   isEquipmentLevel,
+  isOperationalRecord,
   isoDurationHours,
   itemKeyOf,
   levelOfLocationType,
@@ -7462,6 +7780,7 @@ function retiredVocabularyIn(line) {
   objectEvent,
   offCalendarAt,
   offCalendarReasonAt,
+  operationalKindOf,
   operationsCapabilityOf,
   parseEpc,
   parseIsoDuration,

package/package.json

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