@operato/twin-kernel 0.7.45 → 0.7.47

package/dist/contract.d.ts

@@ -2180,7 +2180,19 @@ export interface TwinModelDef {
 export interface ProductionSpec {
     /** 무엇이 있고 어떻게 흐르나 — `DomainDefinition`(자기 타입, zero-dep). */
     definition: import('./domain-definition.ts').DomainDefinition;
-    /** 자재 키 → GS1 item reference. */
+    /**
+     * 자재 키 → **그 자재의 클래스 식별자를 정하는 값.**
+     *
+     * 두 모양을 받는다. `companyPrefix` 가 있으면 값은 GS1 item reference 이고 클래스는
+     * `urn:epc:idpat:sgtin:<prefix>.<ref>.*` 로 조립된다. 프리픽스가 없으면 값은 **이미 완성된 클래스
+     * URI** 이고(CBV 2.0 §8.3.4 `.../class/ObjClassid`) 커널은 그것을 그대로 쓴다 — 조립하면 값을 망친다.
+     *
+     * ── 같은 자재를 가리키는 이름은 하나다 ──────────────────────────────────────
+     * 공정 명세의 `materialSpecification.materialDefinition` 도 **이 값에서 나온 클래스 식별자**여야 한다.
+     * 두 자리가 같은 자재를 다른 이름으로 부르면, 커널은 그것이 같은 자재인지 알 길이 없다 — 같은 산출을
+     * 두 번 만드는 것을 막는 기동 검사가 그때 조용히 열린다(§`assertNoDoubleProduction`). 옮길 수 없는
+     * 식별자는 기동에서 말한다.
+     */
     binding?: Record<string, string>;
     companyPrefix?: string;
     /** 쓸 레시피 키(미지정 시 첫 레시피) — 직렬 생산 경로(MES)만 쓴다. */

package/dist/mes-kernel.d.ts

@@ -107,7 +107,24 @@ export declare class MesKernel extends FlowEngine {
      */
     private recipeDef;
     /** 자재 키 → 구체 gtin 클래스(idpat). 구체 식별은 바인딩+prefix 로 인스턴스가 주입. */
+    /**
+     * 자재 키 → **품목 클래스 식별자.** 선언된 스킴이 모양을 정한다.
+     *
+     * ── 두 길 (2026-08-21) ─────────────────────────────────────────────────────
+     * **프리픽스가 있으면** `binding[key]` 를 품번(itemRef)으로 보고 SGTIN 을 조립한다(예전 거동).
+     * **없으면** `binding[key]` 가 **이미 완성된 클래스 식별자**다 — 커넥터가 선언된 도메인 아래에서
+     * 만든 CBV 형식(`https://<도메인>/class/<id>`)이고, 조립하면 그 값을 망친다.
+     *
+     * 실 연동에서 이것이 드러났다: 커넥터가 `binding` 에 완성된 URI 를 실었는데 커널이 그것을 품번으로
+     * 보고 프리픽스와 이어 붙이려 했다. 선언이 권위이므로 선언된 모양을 그대로 쓴다.
+     */
     private classOf;
+    /**
+     * 자재 키 + 일련번호 → **개체 식별자.**
+     *
+     * 프리픽스가 있으면 SGTIN(직렬), 없으면 선언된 이름공간 아래 CBV §8.2.4 `.../obj/<Objid>`.
+     * `Objid` 는 경로 성분 하나여야 하므로 구분자를 넣지 않는다 — 자재 키와 일련번호를 `-` 로 잇는다.
+     */
     private serialOf;
     /**
      * 이 공정이 **만든다고 선언한 품목** — 표준 `OpMaterialSpecification` `MaterialUse='produced'`.

package/dist/mes-kernel.js

@@ -49,9 +49,27 @@ export class MesKernel extends FlowEngine {
          * 계약에서 `binding`·`companyPrefix` 는 선택이다 — 유통가공(비직렬 클래스+수량)은 자재 명세에
          * gtin 을 직접 적으므로 필요 없다. 그래서 **필요한 경로에서만** 요구하고, 없으면 기동을 막는다.
          */
-        if (productionSpec?.definition?.recipes?.length && (!productionSpec.binding || !productionSpec.companyPrefix)) {
-            throw new Error('recipe-driven production needs `binding` and `companyPrefix` — the definition does not know GTINs, ' +
-                'so material keys cannot be resolved to GS1 identifiers');
+        if (productionSpec?.definition?.recipes?.length) {
+            /*
+             * ── 프리픽스가 없는 현장도 세운다 (2026-08-21) ──────────────────────────
+             * 예전에는 `companyPrefix` 가 없으면 무조건 거절했다. 그래서 **GS1 회사 프리픽스가 없는 실
+             * 시스템이 기동조차 못 했다** — 첫 실 연동(F&B MES)이 정확히 그 자리에서 막혔다.
+             *
+             * 표준은 GS1 키만 인정하지 않는다. 선언된 도메인 아래의 클래스 식별자
+             * (CBV 2.0 §8.3.4 `.../class/<id>`)도 정합이고 소유 권한자는 그 도메인의 주인이다
+             * (EPCIS 2.0 §6.4). 그러면 프리픽스를 요구할 근거가 없다.
+             *
+             * 두 길을 섞지 않는다: 프리픽스가 있으면 SGTIN, 없고 이름공간이 있으면 도메인 기반.
+             * 둘 다 없으면 자재 키를 식별자로 옮길 방법이 없으므로 그때만 거절한다.
+             */
+            const hasPrefix = !!productionSpec.companyPrefix;
+            const hasNamespace = !!productionSpec.identity?.namespaces?.length;
+            if (!productionSpec.binding || !(hasPrefix || hasNamespace)) {
+                throw new Error('recipe-driven production needs `binding`, and either `companyPrefix` (GS1 keys) or ' +
+                    '`identity.namespaces` (domain-based identifiers — CBV 2.0 §8.3.4 `.../class/<id>`, assigned by the ' +
+                    'owner of that internet domain). The definition does not know identifiers, so material keys cannot ' +
+                    'be resolved without one of the two. The kernel does not invent a company prefix.');
+            }
         }
         /* 겹침 검사는 **바인딩 검증 뒤**다 — 검사 자체가 자재 키를 식별자로 옮겨 견주기 때문이다. */
         if (productionSpec?.definition?.operations) {
@@ -71,9 +89,25 @@ export class MesKernel extends FlowEngine {
      * 모든 계산이 거짓이 된다).
      */
     assertNoDoubleProduction(ops) {
-        const finals = new Set((this.productionSpec?.definition?.recipes ?? []).flatMap(r => (r.outputs ?? []).map(o => this.classOf(o.material))));
+        /*
+         * ── 두 어휘를 문자열로 견주지 않는다 (2026-08-21) ──────────────────────────
+         * 예전에는 `classOf(레시피 산출)` 과 `materialSpecification.materialDefinition` 을 **문자열로** 견주었다.
+         * 그 둘은 서로 다른 층의 이름이고(§`materialKeyOfClass`), 우연히 같은 커넥터에서는 맞았다.
+         * 커넥터가 둘을 다르게 실으면 — 공정 명세는 클래스 URI, `binding` 은 품번 — 이 검사가 **조용히
+         * 아무것도 잡지 못한다.** 같은 산출을 두 번 만드는 것을 막으려고 둔 검사인데, 바로 그때 열린다.
+         *
+         * 그래서 양쪽을 **자재 키**로 옮겨 놓고 견준다. 옮길 수 없는 식별자는 그 자리에서 말한다 —
+         * 런타임이 이미 같은 규칙으로 멈추므로(§`materialKeyOfClass`), 기동에서 말하는 편이 낫다.
+         */
+        const finals = new Set((this.productionSpec?.definition?.recipes ?? []).flatMap(r => (r.outputs ?? []).map(o => o.material)));
+        /*
+         * 레시피가 없으면 겹칠 것이 없다 — 그리고 그때는 `binding` 도 없다(유통가공은 산출을 자재 명세로만
+         * 말한다). 옮기기를 시도하면 없는 통로를 지나려 하므로 여기서 끝낸다.
+         */
+        if (!finals.size)
+            return;
         const bad = ops
-            .filter(o => (o.materialSpecification ?? []).some(m => m.use === 'produced' && m.materialDefinition && finals.has(m.materialDefinition)))
+            .filter(o => (o.materialSpecification ?? []).some(m => m.use === 'produced' && m.materialDefinition && finals.has(this.materialKeyOfClass(m.materialDefinition, o.key))))
             .map(o => o.key);
         if (!bad.length)
             return;
@@ -106,7 +140,27 @@ export class MesKernel extends FlowEngine {
      * 아니라 **하나를 고르는** 것이므로 규칙이 갈리지 않는다.
      */
     identityDeclaration() {
-        return this.productionSpec?.identity ?? super.identityDeclaration();
+        /*
+         * ── 가리지 않고 **합친다** (2026-08-21) ────────────────────────────────────
+         * 예전에는 생산 선언이 있으면 모델 선언을 **가렸다**(`?? super`). 그래서 생산 선언이 프리픽스만
+         * 말하고 이름공간은 모델에만 있는 현장에서, 커널이 모델의 이름공간을 보지 못해 작업지시 식별자를
+         * 만들 수 없었다 — 시험이 그것을 잡았다.
+         *
+         * 두 선언은 경쟁이 아니라 같은 사실의 두 자리다(생산 선언은 먼저 생긴 자리다). 항목별로 있는 것을
+         * 쓴다: 생산 선언이 말한 것이 이기고, 말하지 않은 것은 모델에서 온다.
+         */
+        const own = this.productionSpec?.identity;
+        const model = super.identityDeclaration();
+        if (!own)
+            return model;
+        if (!model)
+            return own;
+        return {
+            namespaces: own.namespaces?.length ? own.namespaces : model.namespaces,
+            documentTypes: { ...model.documentTypes, ...own.documentTypes },
+            ...(own.companyPrefix ?? model.companyPrefix ? { companyPrefix: own.companyPrefix ?? model.companyPrefix } : {}),
+            ...(own.issuedClaim ?? model.issuedClaim ? { issuedClaim: own.issuedClaim ?? model.issuedClaim } : {})
+        };
     }
     identityGroundingView() {
         return identityGroundingOf(this.productionSpec);
@@ -264,11 +318,44 @@ export class MesKernel extends FlowEngine {
         return d.recipes[0];
     }
     /** 자재 키 → 구체 gtin 클래스(idpat). 구체 식별은 바인딩+prefix 로 인스턴스가 주입. */
+    /**
+     * 자재 키 → **품목 클래스 식별자.** 선언된 스킴이 모양을 정한다.
+     *
+     * ── 두 길 (2026-08-21) ─────────────────────────────────────────────────────
+     * **프리픽스가 있으면** `binding[key]` 를 품번(itemRef)으로 보고 SGTIN 을 조립한다(예전 거동).
+     * **없으면** `binding[key]` 가 **이미 완성된 클래스 식별자**다 — 커넥터가 선언된 도메인 아래에서
+     * 만든 CBV 형식(`https://<도메인>/class/<id>`)이고, 조립하면 그 값을 망친다.
+     *
+     * 실 연동에서 이것이 드러났다: 커넥터가 `binding` 에 완성된 URI 를 실었는데 커널이 그것을 품번으로
+     * 보고 프리픽스와 이어 붙이려 했다. 선언이 권위이므로 선언된 모양을 그대로 쓴다.
+     */
     classOf(materialKey) {
-        return sgtinClass(this.productionSpec.companyPrefix, this.productionSpec.binding[materialKey]);
+        const spec = this.productionSpec;
+        const bound = spec.binding[materialKey];
+        if (spec.companyPrefix)
+            return sgtinClass(spec.companyPrefix, bound);
+        if (!bound) {
+            throw new Error(`material '${materialKey}' has no binding — the model must say which item this key names. ` +
+                'The kernel does not invent an identifier for it.');
+        }
+        /* 이미 완성된 식별자다. 모양이 표준에 맞는지는 판정기가 답한다(§classIdentifierViolation). */
+        return bound;
     }
+    /**
+     * 자재 키 + 일련번호 → **개체 식별자.**
+     *
+     * 프리픽스가 있으면 SGTIN(직렬), 없으면 선언된 이름공간 아래 CBV §8.2.4 `.../obj/<Objid>`.
+     * `Objid` 는 경로 성분 하나여야 하므로 구분자를 넣지 않는다 — 자재 키와 일련번호를 `-` 로 잇는다.
+     */
     serialOf(materialKey, serial) {
-        return sgtinUri(this.productionSpec.companyPrefix, this.productionSpec.binding[materialKey], serial);
+        const spec = this.productionSpec;
+        if (spec.companyPrefix)
+            return sgtinUri(spec.companyPrefix, spec.binding[materialKey], serial);
+        const uri = this.declaredObjectId(`${materialKey}-${serial}`);
+        if (uri)
+            return uri;
+        throw new Error(`cannot name an instance of '${materialKey}': the model declares neither \`companyPrefix\` (GS1 keys) nor a ` +
+            'usable `identity.namespaces` entry (CBV 2.0 §8.2.4 `.../obj/<id>`). The kernel does not invent one.');
     }
     /**
      * 이 공정이 **만든다고 선언한 품목** — 표준 `OpMaterialSpecification` `MaterialUse='produced'`.
@@ -424,7 +511,8 @@ export class MesKernel extends FlowEngine {
      *    번호라고 말해 주지 않는다.
      */
     workOrderId(serial) {
-        const identity = this.productionSpec.identity;
+        /* 선언을 읽는 곳은 하나다(§`FlowEngine.identityDeclaration`) — 직접 읽으면 모델 자리를 놓친다. */
+        const identity = this.identityDeclaration();
         for (const ns of identity?.namespaces ?? []) {
             const uri = bizTransactionUri(ns, serial);
             if (uri)

package/dist-cjs/index.cjs

@@ -6643,10 +6643,14 @@ var MesKernel = class extends FlowEngine {
     if (productionSpec?.definition?.operations) {
       this.loadOperations(productionSpec.definition.operations);
     }
-    if (productionSpec?.definition?.recipes?.length && (!productionSpec.binding || !productionSpec.companyPrefix)) {
-      throw new Error(
-        "recipe-driven production needs `binding` and `companyPrefix` \u2014 the definition does not know GTINs, so material keys cannot be resolved to GS1 identifiers"
-      );
+    if (productionSpec?.definition?.recipes?.length) {
+      const hasPrefix = !!productionSpec.companyPrefix;
+      const hasNamespace = !!productionSpec.identity?.namespaces?.length;
+      if (!productionSpec.binding || !(hasPrefix || hasNamespace)) {
+        throw new Error(
+          "recipe-driven production needs `binding`, and either `companyPrefix` (GS1 keys) or `identity.namespaces` (domain-based identifiers \u2014 CBV 2.0 \xA78.3.4 `.../class/<id>`, assigned by the owner of that internet domain). The definition does not know identifiers, so material keys cannot be resolved without one of the two. The kernel does not invent a company prefix."
+        );
+      }
     }
     if (productionSpec?.definition?.operations) {
       this.assertNoDoubleProduction(productionSpec.definition.operations);
@@ -6665,8 +6669,13 @@ var MesKernel = class extends FlowEngine {
    * 모든 계산이 거짓이 된다).
    */
   assertNoDoubleProduction(ops) {
-    const finals = new Set((this.productionSpec?.definition?.recipes ?? []).flatMap((r) => (r.outputs ?? []).map((o) => this.classOf(o.material))));
-    const bad2 = ops.filter((o) => (o.materialSpecification ?? []).some((m) => m.use === "produced" && m.materialDefinition && finals.has(m.materialDefinition))).map((o) => o.key);
+    const finals = new Set((this.productionSpec?.definition?.recipes ?? []).flatMap((r) => (r.outputs ?? []).map((o) => o.material)));
+    if (!finals.size) return;
+    const bad2 = ops.filter(
+      (o) => (o.materialSpecification ?? []).some(
+        (m) => m.use === "produced" && m.materialDefinition && finals.has(this.materialKeyOfClass(m.materialDefinition, o.key))
+      )
+    ).map((o) => o.key);
     if (!bad2.length) return;
     throw new Error(
       `MES recipe already produces its output \u2014 operations [${bad2.join(", ")}] must not also declare that same material as materialSpecification use:'produced' (that would create the same output twice). Declare intermediate outputs freely; the final output belongs to the recipe.`
@@ -6697,7 +6706,16 @@ var MesKernel = class extends FlowEngine {
    * 아니라 **하나를 고르는** 것이므로 규칙이 갈리지 않는다.
    */
   identityDeclaration() {
-    return this.productionSpec?.identity ?? super.identityDeclaration();
+    const own = this.productionSpec?.identity;
+    const model = super.identityDeclaration();
+    if (!own) return model;
+    if (!model) return own;
+    return {
+      namespaces: own.namespaces?.length ? own.namespaces : model.namespaces,
+      documentTypes: { ...model.documentTypes, ...own.documentTypes },
+      ...own.companyPrefix ?? model.companyPrefix ? { companyPrefix: own.companyPrefix ?? model.companyPrefix } : {},
+      ...own.issuedClaim ?? model.issuedClaim ? { issuedClaim: own.issuedClaim ?? model.issuedClaim } : {}
+    };
   }
   identityGroundingView() {
     return identityGroundingOf(this.productionSpec);
@@ -6846,11 +6864,42 @@ var MesKernel = class extends FlowEngine {
     return d.recipes[0];
   }
   /** 자재 키 → 구체 gtin 클래스(idpat). 구체 식별은 바인딩+prefix 로 인스턴스가 주입. */
+  /**
+   * 자재 키 → **품목 클래스 식별자.** 선언된 스킴이 모양을 정한다.
+   *
+   * ── 두 길 (2026-08-21) ─────────────────────────────────────────────────────
+   * **프리픽스가 있으면** `binding[key]` 를 품번(itemRef)으로 보고 SGTIN 을 조립한다(예전 거동).
+   * **없으면** `binding[key]` 가 **이미 완성된 클래스 식별자**다 — 커넥터가 선언된 도메인 아래에서
+   * 만든 CBV 형식(`https://<도메인>/class/<id>`)이고, 조립하면 그 값을 망친다.
+   *
+   * 실 연동에서 이것이 드러났다: 커넥터가 `binding` 에 완성된 URI 를 실었는데 커널이 그것을 품번으로
+   * 보고 프리픽스와 이어 붙이려 했다. 선언이 권위이므로 선언된 모양을 그대로 쓴다.
+   */
   classOf(materialKey) {
-    return sgtinClass(this.productionSpec.companyPrefix, this.productionSpec.binding[materialKey]);
+    const spec = this.productionSpec;
+    const bound = spec.binding[materialKey];
+    if (spec.companyPrefix) return sgtinClass(spec.companyPrefix, bound);
+    if (!bound) {
+      throw new Error(
+        `material '${materialKey}' has no binding \u2014 the model must say which item this key names. The kernel does not invent an identifier for it.`
+      );
+    }
+    return bound;
   }
+  /**
+   * 자재 키 + 일련번호 → **개체 식별자.**
+   *
+   * 프리픽스가 있으면 SGTIN(직렬), 없으면 선언된 이름공간 아래 CBV §8.2.4 `.../obj/<Objid>`.
+   * `Objid` 는 경로 성분 하나여야 하므로 구분자를 넣지 않는다 — 자재 키와 일련번호를 `-` 로 잇는다.
+   */
   serialOf(materialKey, serial) {
-    return sgtinUri(this.productionSpec.companyPrefix, this.productionSpec.binding[materialKey], serial);
+    const spec = this.productionSpec;
+    if (spec.companyPrefix) return sgtinUri(spec.companyPrefix, spec.binding[materialKey], serial);
+    const uri = this.declaredObjectId(`${materialKey}-${serial}`);
+    if (uri) return uri;
+    throw new Error(
+      `cannot name an instance of '${materialKey}': the model declares neither \`companyPrefix\` (GS1 keys) nor a usable \`identity.namespaces\` entry (CBV 2.0 \xA78.2.4 \`.../obj/<id>\`). The kernel does not invent one.`
+    );
   }
   /**
    * 이 공정이 **만든다고 선언한 품목** — 표준 `OpMaterialSpecification` `MaterialUse='produced'`.
@@ -6991,7 +7040,7 @@ var MesKernel = class extends FlowEngine {
    *    번호라고 말해 주지 않는다.
    */
   workOrderId(serial) {
-    const identity = this.productionSpec.identity;
+    const identity = this.identityDeclaration();
     for (const ns of identity?.namespaces ?? []) {
       const uri = bizTransactionUri(ns, serial);
       if (uri) return uri;

package/package.json

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