@operato/twin-kernel 0.7.32 → 0.7.33

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/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/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,
@@ -7166,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) {
@@ -7350,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 역사이므로 이름을 바꾸지 않는다 ───────
    * 같은 사실이 시점에 따라 다른 키로 들어가면 낡은 이름보다 나쁘다. 개명은 이벤트 스키마
@@ -7491,10 +7761,12 @@ function retiredVocabularyIn(line) {
   ingest,
   ingestEnergyEquipmentRecords,
   ingestEnergyRecords,
+  ingestOperationalRecords,
   isElectricalLocationType,
   isEnergyEquipmentRecord,
   isEnergyRecord,
   isEquipmentLevel,
+  isOperationalRecord,
   isoDurationHours,
   itemKeyOf,
   levelOfLocationType,
@@ -7508,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.32",
+  "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": {