@operato/twin-kernel 0.7.39 → 0.7.41

package/dist/contract.d.ts

@@ -89,7 +89,7 @@ export interface Hierarchy {
     }): string[];
 }
 /**
- * 계층 색인을 만든다. **순환은 만들 때 잡고 던진다** — 렌더 도중에 터지는 대신 여기서 한 번에.
+ * 계층 색인을 만든다. **순환은 만들 때 잡아 오류를 낸다** — 렌더 도중에 터지는 대신 여기서 한 번에.
  * 순환을 조용히 잘라 내면 롤업이 틀린 값을 내고, 그건 이 함수가 막으려는 바로 그 실패다.
  */
 export declare function hierarchyOf(s: {
@@ -426,6 +426,18 @@ export interface MaterialQuantity {
  *
  * **한 곳에서 정한다.** 소비처마다 `epc` 로 키를 잡으면 같은 로트의 두 부분이 하나로 접히고,
  * 그 순간 재고가 조용히 줄어든다(실제로 그랬다 — §ItemState.subLotId).
+ *
+ * ── 규약 (2026-08-21에 확정) ────────────────────────────────────────────────
+ * ① 물품 맵의 **키는 이 함수의 결과**다. 시뮬·미러 어느 쪽도 규칙을 인라인으로 다시 적지 않는다
+ *    (미러가 `subLotId ?? epc` 를 세 곳에서 다시 적고 있었고, 그런 중복은 한쪽만 고쳐진다).
+ * ② **상태에 실리는 참조도 그 키**다(`TaskState.itemRefs` · `FlowTask.itemEpc`). 그래야 찾기가
+ *    `get` 한 번으로 끝난다. 직렬 물품에서는 키가 곧 `epc` 이므로 대부분의 경로는 이미 그렇다.
+ * ③ 예외는 하나다: **원본이 준 참조**(운영 사실 유입·외부 씨앗)는 우리 키 규칙을 모른다. 그때만
+ *    `FlowEngine.itemByRef` 의 대체 경로(전수 조회)를 지나고, 그 횟수를 `refScanCount()` 가 센다.
+ *    「대체 경로는 드물 것이다」를 짐작하지 않기 위해서다 — 인덱스를 얹을 근거는 그 수다.
+ *
+ * 왜 참조를 키로 통일하고 인덱스를 먼저 얹지 않았나: 키 규약이 두 갈래인 채로 인덱스를 얹으면
+ * **그 질문이 닫힌다**(두 갈래를 전제한 구조가 굳는다). 규약을 먼저 정하고, 남는 비용을 재서 넣는다.
  */
 export declare function subLotIdOf(classUri: string, location: string): string;
 export declare function itemKeyOf(item: {
@@ -1142,6 +1154,15 @@ export interface OrderState {
      * 알 수 없다는 뜻이고, 확보분(`allocated`)이 같은 식으로 빠져 계보의 절반이 사라졌던 것과 같은 부류다.
      */
     gtin?: string;
+    /**
+     * **무엇으로 만드나** — 이 오더가 든 레시피(표준 `OperationsRequest` → `SegmentRequirement`).
+     *
+     * 품목만으로는 「무엇으로」가 남지 않는다: 같은 품목에 대체 레시피가 있을 수 있고, 그러면 소요·라우트·
+     * 소요시간이 다르다. 없으면 소비처는 **묻지 않는다**(레시피가 하나인 트윈이다).
+     */
+    recipeKey?: string;
+    /** 씨앗이 이 오더의 확보분을 다 심지 못했다 — 이 오더의 답은 부족한 씨앗 위에 있다. */
+    seedIncomplete?: boolean;
     progress?: number;
     held?: boolean;
     /**
@@ -1355,14 +1376,22 @@ export interface EnergyState {
     /** 관측 시작 이후 최대 수요 — 월 경계는 여기서 정하지 않는다(위 주석). */
     peakSince?: {
         kW: number;
-        windowStartMs: number; /**
-         * 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — **버린 것을 세어 둔다.**
-         *
-         * 원천에 우리가 모르는 설비가 있다는 것은 그 자체로 알아야 할 사실이다(모델이 낡았거나 매핑이
-         * 틀렸다). 조용히 버리면 「값이 왜 안 보이지」로만 남는다.
-         */
-        unknownEquipment?: number;
+        windowStartMs: number;
     };
+    /**
+     * 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — **버린 것을 세어 둔다.**
+     *
+     * 원천에 우리가 모르는 설비가 있다는 것은 그 자체로 알아야 할 사실이다(모델이 낡았거나 매핑이
+     * 틀렸다). 조용히 버리면 「값이 왜 안 보이지」로만 남는다.
+     *
+     * **자리를 못 박아 둔다**: 이 칸은 `state.energy` 의 것이다 — 스냅샷 루트가 아니다. 예전에는 이 선언이
+     * `peakSince` 의 타입 안에 갇혀 있었다(중괄호 하나가 닫히지 않았다). 타입은 통과했지만 계약이 사실과
+     * 달라서, 읽는 쪽이 자리를 짐작하다 스냅샷 루트에서 읽고 **영원히 `null`** 을 받았다 — 오류 없이
+     * 「에너지 트윈이 아니다」로 읽히는 종류의 거짓이다.
+     *
+     * 0 이면 이 칸을 만들지 않는다. 「세었고 0」과 「에너지 트윈이 아님」은 `energy` 자체가 있는지로 가른다.
+     */
+    unknownEquipment?: number;
     /** 현장이 선언한 계약전력(자리 속성) — 없으면 계약 대비 판정을 하지 않는다. */
     contractKW?: number;
     /**
@@ -1405,6 +1434,25 @@ export interface StateSnapshot {
      * 없으면 소비처는 **재지 않는다** — 벽시계로 대신 재면 시뮬 트윈에서 엉뚱한 값이 나온다.
      */
     nowTime?: ISOTime;
+    /**
+     * **이 트윈의 정체성이 어디서 왔나** — 값이 아니라 **근거**다(§`identityGroundingOf`).
+     *
+     * 트윈당 한 번 싣는다. 사건마다 싣는 것은 비싸고 같은 사실의 반복이다. 없으면 소비처는 **판정하지
+     * 않는다** — 기본값으로 `issued` 를 가정하면 그 화면이 곧 거짓이 된다.
+     */
+    identityGrounding?: IdentityGroundingView;
+    /**
+     * **원본과 어긋난 사실의 수** — 관측(미러) 구동에서만 생긴다.
+     *
+     * 미러는 원본을 비추는 쪽이라 어긋남을 만나도 멈추지 않는다. 그러면 그 사실이 사라지므로 여기 센다.
+     * 없으면(0) 이 칸이 아예 없다 — 어긋난 적 없는 트윈에 빈 칸을 만들지 않는다.
+     */
+    conformance?: {
+        /** 관측 구동에서 없는 입력을 만난 횟수 — 받아들였지만 사실이 맞지 않았다. */
+        transformInputsAbsent?: number;
+        /** 씨앗이 심지 못한 참조의 수 — 원본이 말했지만 그 물품이 스냅샷에 없었다. */
+        seedDanglingRefs?: number;
+    };
     locations: LocationState[];
     items: ItemState[];
     /**
@@ -1483,11 +1531,11 @@ export interface CommandAck {
     error?: string;
 }
 /**
- * 호스트-facing 커맨드 채널(비동기) — 씬 컴포넌트 등 클라이언트가 트윈 호스트에 커맨드를 던지는 계약.
+ * 호스트-facing 커맨드 채널(비동기) — 씬 컴포넌트 등 클라이언트가 트윈 호스트에 커맨드를 보내는 계약.
  * 커널 in-process `dispatch`(동기)와 달리 원격 호스트(GraphQL/HTTP/…) 전송을 추상화.
  * 씬 컨트롤 컴포넌트는 이 인터페이스에만 의존(커널 레벨) — concrete 전송은 각 호스트(things-factory 등)가 주입.
  * → 컴포넌트가 특정 호스트 구현(things-factory)에 갇히지 않고, 어디서든 개발/재사용 가능.
- * 컴포넌트는 tenantId 등을 모르는 부분 커맨드를 던지고, 호스트가 보강한다(commandId/type/args 만 제공).
+ * 컴포넌트는 tenantId 등을 모르는 부분 커맨드를 보내고, 호스트가 보강한다(commandId/type/args 만 제공).
  */
 export interface TwinCommandChannel {
     dispatch(command: Pick<Command, 'commandId' | 'type' | 'args'>): Promise<CommandAck>;
@@ -1875,6 +1923,8 @@ export interface OrderStatusDelta {
      * 잃었던 것과 같은 부류다(패리티 가드가 이것을 잡았다).
      */
     gtin?: string;
+    /** 어느 레시피로 만드는가 — 품목만으로는 「무엇으로」가 남지 않는다(§`FlowOrder.recipeKey`). */
+    recipeKey?: string;
     held?: boolean;
     /**
      * 오더 라인(SKU+수량) — 선택. 있으면 이행 예측이 "남은 데맨드(라인별 requested-fulfilled)를
@@ -2110,7 +2160,123 @@ export interface ProductionSpec {
     companyPrefix?: string;
     /** 쓸 레시피 키(미지정 시 첫 레시피) — 직렬 생산 경로(MES)만 쓴다. */
     recipeKey?: string;
+    /** 이 트윈의 **정체성이 어디서 오나** — §IdentityDeclaration. 없으면 근거는 선언 형태에서 파생된다. */
+    identity?: IdentityDeclaration;
+}
+/**
+ * 정체성 선언 — **이 트윈이 자기 것이라 말하는 이름공간.**
+ *
+ * ── 왜 필요한가 (2026-08-20) ────────────────────────────────────────────────
+ * 커널이 품목 식별자를 지어내고 있었다(`sgtinUri(prefix, 'WIP', …)` · 상수 프리픽스). 그 압력의 출처는
+ * 우리 검증기였다: 수량 리스트의 `epcClass` 에 EPC 형식을 강제했으므로, GS1 프리픽스가 없는 현장은
+ * **통과할 방법이 없었다.** 그래서 지어냈다.
+ *
+ * 원문을 보니 그 강제가 표준의 요구가 아니었다: EPCIS 2.0 §6.4 는 「**소유 권한이 있는** URI」를 요구하고,
+ * CBV 2.0 은 클래스 식별에 일반 HTTP URL 을 명시한다. 즉 **도메인만 있으면 GS1 발급 없이도 정합**이다.
+ * 진입장벽은 우리가 만든 것이었다.
+ *
+ * 그래서 이름공간을 **현장이 선언한다.** 검증은 두 조건의 곱이다: 소유 권한이 있는 형태인가(표준) ∧
+ * 이 트윈이 자기 것이라 선언한 범위인가(모델). 하나만 요구하면 각각 아무 도메인이나 통과하거나,
+ * 소유 권한 없는 스킴이 통과한다.
+ */
+export interface IdentityDeclaration {
+    /**
+     * 이 트윈의 식별자가 속하는 이름공간들 — 예: `https://chef.example.com/product/` ·
+     * `urn:epc:idpat:sgtin:0952000.` · `urn:oid:1.3.6.1.4.1.<PEN>.`
+     *
+     * 커널은 이 목록을 **정하지 않고 묻기만** 한다. 비어 있으면 선언이 없는 것이고, 없는 것을 채우지 않는다.
+     *
+     * **이름공간은 소속만 정한다.** 값의 모양(HTTP URL 의 `/class/` 표지 · URN 의 `:class:`)은 표준이 정하고
+     * `classIdentifierViolation()` 이 판정한다 — 이름공간에 넣었다고 통과하는 것이 아니다.
+     *
+     * **선택이다.** GDTI 문서 타입만 선언하는 현장은 이름공간을 갖지 않는다(§`documentTypes`). 없는 것을
+     * 억지로 적게 하면 그 현장은 빈 목록이나 거짓 이름공간을 쓰게 되고, 그때 근거 판정이 함께 거짓이 된다.
+     */
+    namespaces?: string[];
+    /**
+     * 이 이름공간이 **발급받은 GS1 키**라는 주장.
+     *
+     * **주장이다 — 우리는 검증하지 않는다.** GEPIR 조회를 하지 않으므로 우리가 아는 것은 「모델이 그렇게
+     * 말했다」까지다. 이 칸이 없으면 근거는 `declared` 이고, 그것도 정직한 값이다(형식은 GS1 이어도 출처는
+     * 모델이다 — 실제로 우리 픽스처가 GS1 이 버린 예제 프리픽스를 그 자리에 두고 있었다).
+     */
+    issuedClaim?: boolean;
+    /**
+     * **거래 문서 식별자**(작업지시 등)를 만들 때 쓰는 GDTI **문서 타입** — 종류별로 선언한다.
+     *
+     * ── 왜 이 칸이 필요한가 (2026-08-21) ─────────────────────────────────────
+     * GDTI 는 `회사 프리픽스 + 문서 타입 + 일련번호`이고, **문서 타입은 GS1 이 공표하는 목록이 아니다** —
+     * 프리픽스를 배정받은 회사가 자기 번호 용량에서 정한다. 그런데 커널이 `'403'`(작업지시)·`'401'`·
+     * `'402'`·`'404'` 를 스스로 정해 저널에 영구히 기록하고 있었다. 회사의 배정 권한을 커널이 대신
+     * 행사한 것이고, 프리픽스 날조와 같은 종류의 결함이다.
+     *
+     * **선언하지 않아도 된다.** 표준은 거래 문서 식별자에 GDTI 만 허용하지 않는다 — 선언된 이름공간
+     * 아래 `.../bt/<id>`(CBV §8.5.5) 또는 `urn:<이름공간>:**:bt:<id>`(§8.5.4)가 정합이고, 그쪽이
+     * **회사가 도메인만 있으면 되는** 더 쉬운 길이다. 이 칸은 GDTI 를 쓰는 현장을 위해 열어 둔다.
+     *
+     * 키는 문서의 종류(예: `workorder`), 값은 그 현장이 배정한 문서 타입이다.
+     */
+    documentTypes?: Record<string, string>;
+}
+/**
+ * 정체성의 **근거** — 값이 어디서 왔나. 「우리가 구현했나」와 **다른 축**이다.
+ *
+ * 커버리지 세 축(구조·거동·표면)은 모두 `full` 이면서 그 값이 남의 번호일 수 있다. 그래서 이 축이 없으면
+ * 「정체성 지원 완료」가 참인 동시에 저널에 위조가 쌓인다.
+ *
+ * ── 값마다 **신뢰도가 다르다** ──────────────────────────────────────────────
+ *  · `issued`     — 모델이 발급받았다고 **주장**한 것. 우리는 확인하지 않는다(가장 약한 값).
+ *  · `declared`   — 모델이 선언한 이름공간에서 왔다. 이것은 **확실히 안다**(선언이 근거다).
+ *  · `fabricated` — 코드 리터럴에서 왔다. 이것도 확실히 안다 — 그리고 **릴리즈를 통과해선 안 된다.**
+ *
+ * 어댑터의 `grounding`(`vendor-doc`·`standard`·`facsimile`)과 낱말은 겹치지만 **값 집합이 다르다**:
+ * 저쪽은 「우리 매핑의 근거가 무엇인가」, 이쪽은 「식별자가 어디서 왔는가」다. 서로 대입하지 말 것.
+ *
+ * ── 표준의 권고는 여전히 EPC URI 다 ────────────────────────────────────────
+ * CBV 2.0 §8.3.3·§8.3.4 는 둘 다 이렇게 말한다: *"both CBV-Compliant and CBV-Compatible documents **SHOULD**
+ * use the EPC URI form unless there is a **strong** reason to do otherwise."* 즉 「사내 식별자도 표준이다」는
+ * 맞지만, 표준이 **권하는 것은 GS1 키**다. 「GS1 프리픽스가 없다」가 그 strong reason 에 해당한다.
+ * 이 축은 GS1 을 권하지 않으려고 있는 것이 아니라, **없는 현장을 막지 않으려고** 있다.
+ *
+ * ── 이름공간에 든다고 통과가 아니다 ────────────────────────────────────────
+ * 판정은 두 겹이고 **서로 다른 것을 본다**:
+ *  · (a) **모양** — 소유 권한을 말할 수 있는 형태인가. HTTP(S) URL 은 `…/class/<Objclassid>` 표지가
+ *    **필수**이고(CBV §8.3.4), URN 은 `…:class:<Objclassid>` 가 필수다(§8.3.3). 즉 이름공간이
+ *    `https://chef.example.com` 이어도 값이 `…/product/<uuid>` 면 **부적합**하다 — `…/class/<uuid>` 여야 한다.
+ *  · (b) **소속** — 그 값이 `namespaces` 가 말한 범위 안인가.
+ *
+ * (a) 의 규칙은 한 곳에만 있다: `epcis.ts` 의 `classIdentifierViolation()`. 소비처는 그것을 **부르고**,
+ * 규칙을 다시 적지 않는다(두 벌이 되면 한쪽만 고쳐진다).
+ */
+export type IdentityGrounding = 'issued' | 'declared' | 'fabricated';
+/** 근거 판정 — 값과, 왜 그 값인지, 그리고 검증기가 쓸 이름공간. */
+export interface IdentityGroundingView {
+    grounding: IdentityGrounding;
+    /**
+     * 그 판정의 근거 자리 — 화면·게이트가 「왜」를 말할 수 있게.
+     *  · `claimed-issued`   — 모델이 발급을 주장했다
+     *  · `declared-namespace` — 모델이 이름공간을 선언했다
+     *  · `gs1-shaped`       — `companyPrefix`+`binding` 은 있으나 발급 주장은 없다(형식만 GS1)
+     *  · `kernel-constant`  — 선언이 없어 커널 상수로 돈다(레거시 내장 시나리오)
+     */
+    basis: 'claimed-issued' | 'declared-namespace' | 'gs1-shaped' | 'kernel-constant';
+    /**
+     * 이 트윈이 자기 것이라 선언한 이름공간들 — 검증기의 두 번째 조건이 이것을 쓴다.
+     *
+     * 선언이 없는 레거시 트윈에는 **커널 상수에서 파생된** 값이 들어온다. 그것이 통과를 만들어 주지만
+     * 정직성은 `grounding: 'fabricated'` 가 지킨다 — 릴리즈 게이트가 그 값으로 막는다. 레거시 경로의
+     * 사건을 여기서 거절하면 그 트윈은 아무 사실도 남기지 못하는데, 그건 지금 고치는 문제가 아니다.
+     */
+    namespaces: string[];
 }
+/**
+ * 선언에서 근거를 **파생한다** — 새 사실을 만들지 않는다.
+ *
+ * `companyPrefix` 가 있다는 사실을 `issued` 로 읽지 **않는다**: 그 값이 이 회사에 발급되었다는 뜻이
+ * 아니기 때문이다(우리 픽스처가 반례다 — GS1 이 2022 년에 버린 예제 프리픽스 `0614141` 이 그 자리에
+ * 있었다). 발급은 모델이 **따로 말해야** 하고, 그것도 주장이다.
+ */
+export declare function identityGroundingOf(spec: ProductionSpec | undefined, kernelConstantPrefix?: string): IdentityGroundingView;
 /**
  * 공장을 전환한 결과 — **몇 개가 늘고 몇 개가 사라졌나.**
  *

package/dist/contract.js

@@ -57,7 +57,7 @@ export function isEquipmentLevel(v) {
     return typeof v === 'string' && EQUIPMENT_LEVEL.includes(v);
 }
 /**
- * 계층 색인을 만든다. **순환은 만들 때 잡고 던진다** — 렌더 도중에 터지는 대신 여기서 한 번에.
+ * 계층 색인을 만든다. **순환은 만들 때 잡아 오류를 낸다** — 렌더 도중에 터지는 대신 여기서 한 번에.
  * 순환을 조용히 잘라 내면 롤업이 틀린 값을 내고, 그건 이 함수가 막으려는 바로 그 실패다.
  */
 export function hierarchyOf(s, 
@@ -150,7 +150,7 @@ export function testPassedAt(r, at) {
         return false;
     if (!r.expiresAt || !at)
         return r.result === 'pass';
-    return Date.parse(at) <= Date.parse(r.expiresAt);
+    return parsedMs(at) <= parsedMs(r.expiresAt);
 }
 /**
  * 이 개체가 **요구된 시험들을 만족하나** — 등급이 요구하고 개체가 기록을 든다.
@@ -293,8 +293,8 @@ export function priorityRank(p) {
 export function dueStatusOf(x, nowIso) {
     if (!x.endTime || !nowIso)
         return undefined;
-    const due = Date.parse(x.endTime);
-    const now = Date.parse(nowIso);
+    const due = parsedMs(x.endTime);
+    const now = parsedMs(nowIso);
     if (!Number.isFinite(due) || !Number.isFinite(now))
         return undefined;
     return now > due ? 'late' : 'on-time';
@@ -316,6 +316,18 @@ export function dueStatusOf(x, nowIso) {
  *
  * **한 곳에서 정한다.** 소비처마다 `epc` 로 키를 잡으면 같은 로트의 두 부분이 하나로 접히고,
  * 그 순간 재고가 조용히 줄어든다(실제로 그랬다 — §ItemState.subLotId).
+ *
+ * ── 규약 (2026-08-21에 확정) ────────────────────────────────────────────────
+ * ① 물품 맵의 **키는 이 함수의 결과**다. 시뮬·미러 어느 쪽도 규칙을 인라인으로 다시 적지 않는다
+ *    (미러가 `subLotId ?? epc` 를 세 곳에서 다시 적고 있었고, 그런 중복은 한쪽만 고쳐진다).
+ * ② **상태에 실리는 참조도 그 키**다(`TaskState.itemRefs` · `FlowTask.itemEpc`). 그래야 찾기가
+ *    `get` 한 번으로 끝난다. 직렬 물품에서는 키가 곧 `epc` 이므로 대부분의 경로는 이미 그렇다.
+ * ③ 예외는 하나다: **원본이 준 참조**(운영 사실 유입·외부 씨앗)는 우리 키 규칙을 모른다. 그때만
+ *    `FlowEngine.itemByRef` 의 대체 경로(전수 조회)를 지나고, 그 횟수를 `refScanCount()` 가 센다.
+ *    「대체 경로는 드물 것이다」를 짐작하지 않기 위해서다 — 인덱스를 얹을 근거는 그 수다.
+ *
+ * 왜 참조를 키로 통일하고 인덱스를 먼저 얹지 않았나: 키 규약이 두 갈래인 채로 인덱스를 얹으면
+ * **그 질문이 닫힌다**(두 갈래를 전제한 구조가 굳는다). 규약을 먼저 정하고, 남는 비용을 재서 넣는다.
  */
 export function subLotIdOf(classUri, location) {
     return `${classUri}@${location}`;
@@ -651,7 +663,7 @@ export function capabilityOf(r, ctx) {
     if (r.status === 'down')
         return { available: false, reason: 'down' };
     if (at) {
-        const ms = Date.parse(at);
+        const ms = parsedMs(at);
         if (Number.isFinite(ms)) {
             const why = offCalendarReasonAt(r, ms, ctx?.utcOffsetMinutes);
             if (why === 'non-working')
@@ -812,3 +824,32 @@ export function readBoardAssets(def) {
     const list = (def.assets ?? []);
     return list.map(a => normalizeHomeLocation(a));
 }
+/**
+ * 선언에서 근거를 **파생한다** — 새 사실을 만들지 않는다.
+ *
+ * `companyPrefix` 가 있다는 사실을 `issued` 로 읽지 **않는다**: 그 값이 이 회사에 발급되었다는 뜻이
+ * 아니기 때문이다(우리 픽스처가 반례다 — GS1 이 2022 년에 버린 예제 프리픽스 `0614141` 이 그 자리에
+ * 있었다). 발급은 모델이 **따로 말해야** 하고, 그것도 주장이다.
+ */
+export function identityGroundingOf(spec, kernelConstantPrefix) {
+    const declared = spec?.identity?.namespaces?.filter(n => typeof n === 'string' && n.length > 0) ?? [];
+    if (spec?.identity?.issuedClaim && declared.length) {
+        return { grounding: 'issued', basis: 'claimed-issued', namespaces: [...declared] };
+    }
+    if (declared.length)
+        return { grounding: 'declared', basis: 'declared-namespace', namespaces: [...declared] };
+    if (spec?.companyPrefix && spec.binding) {
+        /* 형식은 GS1 이지만 출처는 모델이다 — 그 프리픽스가 발급되었다는 근거가 우리에게 없다. */
+        return { grounding: 'declared', basis: 'gs1-shaped', namespaces: gs1Namespaces(spec.companyPrefix) };
+    }
+    /* 선언이 없다 — 이 트윈은 커널 상수로 돈다. 그 사실을 값으로 말한다. */
+    return {
+        grounding: 'fabricated',
+        basis: 'kernel-constant',
+        namespaces: kernelConstantPrefix ? gs1Namespaces(kernelConstantPrefix) : []
+    };
+}
+/** 회사 프리픽스가 정하는 GS1 이름공간들 — 커널이 값을 고르지 않고 선언을 펼친다. */
+function gs1Namespaces(prefix) {
+    return [`urn:epc:idpat:sgtin:${prefix}.`, `urn:epc:class:lgtin:${prefix}.`, `urn:epc:id:sgtin:${prefix}.`];
+}

package/dist/domain-catalog.d.ts

@@ -225,7 +225,7 @@ export declare const propertiesOf: (axis: string) => TwinPropertyInfo[];
  */
 export declare const axisSource: (axis: string) => "document" | "state" | "journal";
 /**
- * 문서에서 이 축을 찾을 자리 — **문서 축이 아니면 던진다.**
+ * 문서에서 이 축을 찾을 자리 — **문서 축이 아니면 오류를 낸다.**
  *
  * 상태·저널 축에는 board 안의 자리가 없다. 그런데 옛 소비처는 `info.path` 를 무조건 읽었으므로,
  * 그 자리가 `undefined` 면 board 루트를 읽고 **오류 없이 0 을 답한다**(이 프로젝트가 겪은 실패 모양).

package/dist/domain-catalog.js

@@ -202,7 +202,7 @@ export const propertiesOf = (axis) => TWIN_PROPERTIES.filter(p => p.axis === axi
  */
 export const axisSource = (axis) => TWIN_AXES.find(a => a.axis === axis)?.source ?? 'document';
 /**
- * 문서에서 이 축을 찾을 자리 — **문서 축이 아니면 던진다.**
+ * 문서에서 이 축을 찾을 자리 — **문서 축이 아니면 오류를 낸다.**
  *
  * 상태·저널 축에는 board 안의 자리가 없다. 그런데 옛 소비처는 `info.path` 를 무조건 읽었으므로,
  * 그 자리가 `undefined` 면 board 루트를 읽고 **오류 없이 0 을 답한다**(이 프로젝트가 겪은 실패 모양).

package/dist/domain-definition.d.ts

@@ -29,6 +29,23 @@ export interface MaterialDef {
     key: string;
     label: string;
     identity?: Identity;
+    /**
+     * 이 자재가 놓이는 자리 타입(`LocationTypeDef.key`) — **보관처는 자재의 성질이다.**
+     *
+     * 이 자리가 없던 동안 커널은 `'raw-store'`·`'fg-store'` 라는 이름을 **코드에 박아 두고** 있었다.
+     * 그래서 현장은 자기 창고를 그 이름으로 **개명해야** 트윈이 굴러갔다 — 커널이 현장의 낱말을 정하는
+     * 셈이고, 개명하지 않은 트윈은 조용히 멈추거나(자재가 영원히 안 들어옴) 터졌다.
+     *
+     * **왜 레시피 줄이 아니라 자재인가**: 같은 밀가루를 쓰는 레시피가 열이면 줄마다 같은 값을 열 번
+     * 적게 되고, 창고를 옮길 때 열 곳을 고쳐야 한다. 보관처는 제품 구조(BOM)의 성질이 아니다 —
+     * 실 시스템도 그렇게 두지 않는다: 조사한 식음료 MES 에서 **품목이 창고를 들고 BOM 줄에는 없었다.**
+     * (커널은 어느 제품에도 기대지 않는다 — 실 시스템은 이 결함이 실재한다는 **증인**이고, 커널의 모양을
+     * 정하는 것은 표준과 원칙이다.)
+     *
+     * 선택 필드로 둔 것은 자재를 선언만 하고 쓰지 않는 정의를 막지 않으려는 것이다. **레시피가 쓰는
+     * 자재는 이것을 반드시 선언해야 한다** — `validateDomainDefinition` 이 그때 위반으로 잡는다.
+     */
+    locationType?: string;
 }
 /** 로케이션(수동 위치) 타입. */
 export interface LocationTypeDef {

package/dist/domain-definition.js

@@ -48,6 +48,7 @@ export function validateDomainDefinition(def) {
     const locationKeys = new Set((def.locationTypes || []).map(n => n.key));
     const resKeys = new Set((def.resourceTypes || []).map(r => r.key));
     const matKeys = new Set((def.materials || []).map(m => m.key));
+    const matByKey = new Map((def.materials || []).map(m => [m.key, m]));
     const opKeys = new Set((def.operations || []).map(o => o.key));
     const routeKeys = new Set((def.routes || []).map(r => r.key));
     for (const [name, arr] of [['locationTypes', def.locationTypes], ['resourceTypes', def.resourceTypes], ['materials', def.materials], ['operations', def.operations], ['routes', def.routes], ['recipes', def.recipes]]) {
@@ -81,6 +82,12 @@ export function validateDomainDefinition(def) {
                 v.push(`recipe '${rc.key}' material '${p.material}' 미정의`);
             if (typeof p.qty !== 'number' || p.qty <= 0)
                 v.push(`recipe '${rc.key}' material '${p.material}' qty 부정`);
+            /* 레시피가 쓰는 자재는 자기 자리를 말해야 한다 — 커널은 그것을 지어내지 않는다(MaterialDef.locationType). */
+            const mat = matByKey.get(p.material);
+            if (mat && !mat.locationType)
+                v.push(`recipe '${rc.key}' material '${p.material}' locationType 미선언`);
+            if (mat?.locationType && !locationKeys.has(mat.locationType))
+                v.push(`recipe '${rc.key}' material '${p.material}' locationType '${mat.locationType}' 미정의`);
         }
     }
     return v;

package/dist/ems-kernel.js

@@ -436,6 +436,18 @@ export class EmsKernel extends FlowEngine {
                 startMs: w.startMs,
                 endMs: w.endMs,
                 ...(w.maxKW !== undefined ? { maxKW: w.maxKW } : {}),
+                /*
+                 * ── 선언된 것만의 합도 **사실로 남긴다** (2026-08-20) ────────────────────
+                 *
+                 * 상태에만 두면 저널을 읽는 쪽(성과·타임라인·요금 화면)은 총합만 본다. 실 서버에서 확인한 모양이
+                 * 그랬다: 유령 계량기 300kW 가 섞인 구간이 「계약 1,000 초과 1,100」으로만 남고, 그중 얼마가
+                 * 정체 모를 계량기인지 되짚을 길이 없었다. 지나간 구간의 두 수는 나중에 계산할 수 없다 —
+                 * 그 순간의 지점별 kW 를 커널이 보관하지 않기 때문이다.
+                 *
+                 * `overContract` 는 여기서도 총합으로만 판정한다(요금이 그렇게 매겨진다). 선언된 것만으로는
+                 * 넘지 않았다는 판단은 **읽는 쪽이** 이 두 수로 한다 — 판정을 두 벌 만들지 않는다.
+                 */
+                ...(w.maxDeclaredKW !== undefined ? { maxDeclaredKW: w.maxDeclaredKW } : {}),
                 /* 총부하도 사실로 남긴다 — 이것이 없으면 저널을 읽는 쪽은 「무엇이 깎였나」를 되짚을 수 없다
                    (요금은 순수요로 매겨지지만, 그 수요를 만든 것은 설비 부하다). */
                 ...(w.grossMaxKW !== undefined ? { grossMaxKW: w.grossMaxKW } : {}),
@@ -609,7 +621,7 @@ export class EmsKernel extends FlowEngine {
      * **아무 일도 하지 않는다** — 그런데 조용히 넘기지 않는다: 이 커널이 그런 요청을 받았다는 것은
      * **배선이 잘못됐다는 사실**이고(EMS 트윈에 물류 명령을 보낸 것), 조용히 넘기면 그 사실이 사라진다.
      *
-     * 던지지도 않는다: 저널 재생 중이라면 트윈 전체가 멈춘다. 그래서 커널이 담을 줄 모르는 사건을
+     * 오류를 내지도 않는다: 저널 재생 중이라면 트윈 전체가 멈춘다. 그래서 커널이 담을 줄 모르는 사건을
      * 세는 자리(`ObservedReducer.unhandled`)와 같은 규율으로, **개수를 세어 상태로 낸다.**
      */
     flowRequests = new Map();

package/dist/epcis.d.ts

@@ -252,6 +252,26 @@ export interface ParsedEpc {
 export declare function parseEpc(uri: string): ParsedEpc;
 /** 거래문서 식별자 = GDTI (PO/SO/WO/어포인트먼트 등). */
 export declare function gdtiUri(companyPrefix: string, docType: string, serial: number): string;
+/**
+ * **선언된 이름공간 아래의 거래 문서 식별자** — GDTI 를 쓰지 않는 길.
+ *
+ * ── 왜 이 길이 필요한가 (2026-08-21) ───────────────────────────────────────
+ * GDTI 는 `회사 프리픽스 + 문서 타입 + 일련번호`이고 **문서 타입은 회사가 배정한다**(GS1 이 공표하는
+ * 목록이 아니다). 그런데 커널이 `'403'`(작업지시)·`'401'`·`'402'`·`'404'` 를 스스로 정하고 있었다.
+ *
+ * 표준은 거래 문서 식별자에 GDTI 만 요구하지 않는다. CBV 2.0 이 세 형태를 더 정한다:
+ *  · §8.5.5 `http(s)://[Subdomain.]Domain/⁎⁎/bt/transID` — 그 도메인 소유자가 배정
+ *  · §8.5.4 `urn:URNNamespace:⁎⁎:bt:transID` — URN 이름공간 소유자가 배정
+ *  · §8.5.3 `urn:epcglobal:cbv:bt:gln:transID` — GLN 소유자가 배정
+ *
+ * `bt` 표지가 **필수**이고, `transID` 는 경로 성분 **하나**다(「only one URI path component SHALL
+ * follow the /bt/」). 그래서 회사가 **도메인만 있으면** 문서 타입을 정할 일이 없다 — 이것이 GDTI 보다
+ * 진입장벽이 낮은 길이다.
+ *
+ * 이름공간의 모양으로 URL 형태와 URN 형태를 가른다. 판정할 수 없는 모양이면 **답하지 않는다**(지어내지
+ * 않는다) — 호출부가 다른 길을 고르게 한다.
+ */
+export declare function bizTransactionUri(namespace: string, transId: string | number): string | undefined;
 /** 모든 빌더가 공통으로 받는 표준 헤더 옵션(선택) — 방출부가 필요할 때 채운다. */
 export interface EpcisHeaderOptions {
     eventID?: string;
@@ -312,5 +332,7 @@ export declare function transformationEvent(p: {
     bizLocation?: string;
     bizTransactionList?: BizTransactionElement[];
 } & EpcisHeaderOptions): EpcisTransformationEvent;
+/** 위반 문구, 또는 통과면 `undefined`. */
+export declare function classIdentifierViolation(epcClass: string | undefined): string | undefined;
 export declare function validateEpcisEvent(e: EpcisEvent): string[];
 export {};

package/dist/epcis.js

@@ -113,6 +113,46 @@ export function parseEpc(uri) {
 export function gdtiUri(companyPrefix, docType, serial) {
     return `urn:epc:id:gdti:${companyPrefix}.${docType}.${serial}`;
 }
+/**
+ * **선언된 이름공간 아래의 거래 문서 식별자** — GDTI 를 쓰지 않는 길.
+ *
+ * ── 왜 이 길이 필요한가 (2026-08-21) ───────────────────────────────────────
+ * GDTI 는 `회사 프리픽스 + 문서 타입 + 일련번호`이고 **문서 타입은 회사가 배정한다**(GS1 이 공표하는
+ * 목록이 아니다). 그런데 커널이 `'403'`(작업지시)·`'401'`·`'402'`·`'404'` 를 스스로 정하고 있었다.
+ *
+ * 표준은 거래 문서 식별자에 GDTI 만 요구하지 않는다. CBV 2.0 이 세 형태를 더 정한다:
+ *  · §8.5.5 `http(s)://[Subdomain.]Domain/⁎⁎/bt/transID` — 그 도메인 소유자가 배정
+ *  · §8.5.4 `urn:URNNamespace:⁎⁎:bt:transID` — URN 이름공간 소유자가 배정
+ *  · §8.5.3 `urn:epcglobal:cbv:bt:gln:transID` — GLN 소유자가 배정
+ *
+ * `bt` 표지가 **필수**이고, `transID` 는 경로 성분 **하나**다(「only one URI path component SHALL
+ * follow the /bt/」). 그래서 회사가 **도메인만 있으면** 문서 타입을 정할 일이 없다 — 이것이 GDTI 보다
+ * 진입장벽이 낮은 길이다.
+ *
+ * 이름공간의 모양으로 URL 형태와 URN 형태를 가른다. 판정할 수 없는 모양이면 **답하지 않는다**(지어내지
+ * 않는다) — 호출부가 다른 길을 고르게 한다.
+ */
+export function bizTransactionUri(namespace, transId) {
+    const ns = namespace?.trim();
+    if (!ns)
+        return undefined;
+    const id = String(transId);
+    /* `transID` 에 구분자가 들어가면 표준이 요구하는 「성분 하나」가 깨진다. */
+    if (!id || id.includes('/') || id.includes(':'))
+        return undefined;
+    if (/^https?:\/\/[^/\s]+/.test(ns))
+        return `${ns.replace(/\/+$/, '')}/bt/${id}`;
+    /*
+     * **GS1 이 소유한 URN 공간에는 우리가 `:bt:` 를 만들 수 없다.** `urn:epc:`·`urn:epcglobal:` 의
+     * 소유 권한자는 GS1 이고(EPCIS §6.4), 그 안의 형태는 표준이 정해 둔 것만 유효하다. 그 공간을
+     * 이름공간으로 선언한 현장은 GDTI 문서 타입을 선언하는 쪽으로 가야 한다.
+     */
+    if (/^urn:epc(global)?:/.test(ns))
+        return undefined;
+    if (/^urn:[^:\s]+/.test(ns))
+        return `${ns.replace(/:+$/, '')}:bt:${id}`;
+    return undefined;
+}
 function header(type, eventTime, bizStep, opts) {
     const h = {
         '@context': EPCIS_CONTEXT,
@@ -221,6 +261,54 @@ export function transformationEvent(p) {
 const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
 const TZ_RE = /^[+-]\d{2}:\d{2}$/;
 const ACTIONS = ['ADD', 'OBSERVE', 'DELETE'];
+/*
+ * ★ 클래스 식별자 판정 — **표준이 요구하는 것은 GS1 발급이 아니라 「소유 권한」이다.**
+ *
+ * ── 무엇이 틀렸나 (2026-08-20) ──────────────────────────────────────────────
+ * 예전에는 `urn:epc:idpat:` · `urn:epc:class:` **둘만** 통과시켰다. 그래서 GS1 회사 프리픽스가 없는
+ * 현장은 **통과할 길이 없었고**, 통과시키려면 프리픽스를 지어내야 했다. 커널의 `0614141`(GS1 이 예제로
+ * 쓰다 버린 값, 실 배정 대역)이 그 압력의 산물이다. **막는 쪽이 위조의 원인이었다.**
+ *
+ * ── 원문 (Release 2.0, Ratified Jun 2022) ──────────────────────────────────
+ * EPCIS 2.0 §6.4: "The types of URIs admissible as Vocabulary Elements are those URIs **for which
+ * there is an owning authority.**" — EPC URI · 절대 URL(도메인 소유자) · PEN 기반 `oid` URN ·
+ * `epc`/`epcglobal` URN · GS1 Digital Link.
+ * EPCIS 2.0 §6.2: `epcClass`(Object Class) 는 **User Vocabulary** 다.
+ *
+ * CBV 2.0 이 클래스 식별자의 **모양**을 규정한다:
+ *  · §8.3.3 `urn:URNNamespace:**:class:ObjClassid` — URN 이름공간 소유자가 배정
+ *  · §8.3.4 `http(s)://[Subdomain.]Domain/⁎⁎/class/ObjClassid` — 그 인터넷 도메인 소유자가 배정
+ *    (`ObjClassid` 에 `/` 불가 — "only one URI path component SHALL follow the /class/")
+ *
+ * `class` 표지가 **필수**다. 그냥 절대 URL 이면 되는 것이 아니다 —
+ * `https://chef.example.com/product/<uuid>` 는 **부적합**이고 `.../class/<uuid>` 가 적합이다.
+ *
+ * ── 아직 판정하지 않는 것 (좁힘을 드러내 둔다) ──────────────────────────────
+ * **비정규형 GS1 Digital Link**(§8.3.2 의 `https://example.com/some/path/info/8003/…` 류)는 거절한다.
+ * 정규형(`https://id.gs1.org/…`)만 받는다. 판정에 GS1 Application Identifier 지식이 필요하고 지금
+ * 소비처가 없다. **표준보다 좁은 것을 알고 있다** — Digital Link 를 쓰는 원천이 붙는 날 이 절을 연다.
+ */
+const EPC_CLASS_PREFIXES = ['urn:epc:idpat:', 'urn:epc:class:'];
+/** CBV §8.3.2 정규형 Digital Link. 비정규형은 위 주석대로 아직 판정하지 않는다. */
+const DL_CANONICAL = 'https://id.gs1.org/';
+/** CBV §8.3.4 — 도메인 소유자가 배정. `ObjClassid` 는 경로 성분 **하나**(RFC3986 segment-nz). */
+const CBV_URL_CLASS = /^https?:\/\/[^/\s]+\/(?:[^/\s]+\/)*class\/[^/\s]+$/;
+/** CBV §8.3.3 — URN 이름공간 소유자가 배정. `ObjClassid` 에 콜론 불가. */
+const CBV_URN_CLASS = /^urn:[^:\s]+:(?:[^:\s]+:)*class:[^:\s]+$/;
+/** 위반 문구, 또는 통과면 `undefined`. */
+export function classIdentifierViolation(epcClass) {
+    if (!epcClass)
+        return `quantity epcClass 부정: ${epcClass}`;
+    if (EPC_CLASS_PREFIXES.some(p => epcClass.startsWith(p)))
+        return undefined;
+    if (epcClass.startsWith(DL_CANONICAL))
+        return undefined;
+    if (CBV_URL_CLASS.test(epcClass) || CBV_URN_CLASS.test(epcClass))
+        return undefined;
+    return (`quantity epcClass 부정: ${epcClass} — 클래스 식별자는 소유 권한을 말할 수 있는 모양이어야 한다 ` +
+        `(EPC 클래스 urn:epc:idpat:/urn:epc:class: · CBV §8.3.4 http(s)://<도메인>/**/class/<id> · ` +
+        `CBV §8.3.3 urn:<이름공간>:**:class:<id>)`);
+}
 export function validateEpcisEvent(e) {
     const v = [];
     if (e['@context'] !== EPCIS_CONTEXT)
@@ -323,8 +411,9 @@ export function validateEpcisEvent(e) {
     for (const list of qtyLists)
         for (const q of list ?? []) {
             /* 클래스 식별자만 — 개체(urn:epc:id:)는 epcList 의 몫이다. */
-            if (!q.epcClass?.startsWith('urn:epc:idpat:') && !q.epcClass?.startsWith('urn:epc:class:'))
-                v.push(`quantity epcClass 부정: ${q.epcClass}`);
+            const bad = classIdentifierViolation(q.epcClass);
+            if (bad)
+                v.push(bad);
             /* 세 경우(EPCIS 2.0 §7.3.3.1) — 느슨하게 통과시키면 "모름" 과 "0" 이 섞인다. */
             const hasQty = q.quantity !== undefined && q.quantity !== null;
             if (!hasQty) {

package/dist/face2-adapter.d.ts

@@ -8,7 +8,27 @@ export interface ObjectEventMapping {
     action: MapValue;
     bizStep: MapValue;
     disposition?: MapValue;
-    epc: MapValue;
+    /**
+     * 개체 하나의 식별자 → `epcList: [epc]`. **`quantityList` 를 쓰면 없어도 된다** — 낱개 번호가 없는
+     * 자재(밀가루 3.5kg)는 개체가 없다. 둘 다 없으면 무엇을 관측했는지 말하지 않은 것이므로 오류다.
+     */
+    epc?: MapValue;
+    /**
+     * 클래스와 수량 → `quantityList` (`{ epcClass, quantity, uom? }` 배열).
+     *
+     * ── 왜 뒤늦게 생겼나 (2026-08-20) ───────────────────────────────────────────
+     * `AggregationEventMapping.childQuantityList` 가 같은 이유로 하루 먼저 생겼다(적재를 말할 길이 없었다).
+     * 개체 관측에는 그 자리가 없어서, **원본이 「이 자리에 이 품목이 얼마 남았다」를 말할 길이 없었다.**
+     * 받는 쪽은 처음부터 준비돼 있었다 — `ObservedReducer` 는 `quantityList` 를 읽고, 개체 없이 수량만 오는
+     * 경우까지 따로 다룬다(비직렬 자재는 클래스 식별자가 곧 물품의 키다). 검증도 유효로 판정한다
+     * (`epcList` 와 `quantityList` 가 **둘 다** 비었을 때만 오류). 문만 없었다.
+     *
+     * 비직렬 수량이 주된 경로인 원본(식품 제조 MES)은 이 자리가 없으면 라이브를 낼 수 없다.
+     *
+     * **잔량 절대값을 싣는다** — 「얼마 뺐다」가 아니라 「얼마 남았다」다. 그래야 사건 하나를 놓쳐도 다음
+     * 사건이 정답을 다시 말해 주고 오차가 쌓이지 않는다(시뮬 `consumeMaterials` 가 택한 것과 같은 규약).
+     */
+    quantityList?: MapValue;
     readPoint?: MapValue;
     bizLocation?: MapValue;
 }

package/dist/face2-adapter.js

@@ -104,8 +104,19 @@ export function mapRecordChecked(record, mapping, eventTime) {
         };
     }
     const epc = resolve(mapping.epc, record, 'epc', errors);
+    const quantityList = resolveQuantityList(mapping.quantityList, record, 'quantityList', errors);
+    /* 개체도 수량도 없으면 무엇을 관측했는지 말하지 않은 것이다 — 검증에 넘기기 전에 여기서 말해 준다
+       (검증 메시지는 이벤트를 가리키고, 이 메시지는 **매핑**을 가리킨다: 커넥터가 고칠 곳이 다르다). */
+    if (!epc && !quantityList.length) {
+        errors.push('epc 와 quantityList 가 둘 다 비었다 — 개체 식별자나 클래스+수량 중 하나는 있어야 한다');
+    }
     return {
-        event: objectEvent({ eventTime, action, bizStep, disposition, epcList: epc ? [epc] : [], readPoint, bizLocation }),
+        event: objectEvent({
+            eventTime, action, bizStep, disposition,
+            epcList: epc ? [epc] : [],
+            ...(quantityList.length ? { quantityList } : {}),
+            readPoint, bizLocation
+        }),
         errors
     };
 }