@things-factory/headless-twin 10.1.141 → 10.1.143

package/dist-server/engine/model-refusal.d.ts

@@ -0,0 +1,3 @@
+export declare function asModelRefusal(error: unknown, instanceId: string): unknown;
+/** Run a step that loads or replays a model; a kernel refusal comes out as a `Refusal`. */
+export declare function refusingModel<T>(instanceId: string, step: () => T): T;

package/dist-server/engine/model-refusal.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asModelRefusal = asModelRefusal;
+exports.refusingModel = refusingModel;
+const shell_1 = require("@things-factory/shell");
+/*
+ * **A twin model the kernel refuses is said by name** (ADR-0054).
+ *
+ * ── What went wrong (2026-10-10) ─────────────────────────────────────────────
+ * The MES kernel refuses a model without a production declaration. The engine let that error through
+ * as it was, so `twinReplay(miratek)` reached the screen as INTERNAL_SERVER_ERROR with the kernel's
+ * English sentence in the shell's notice. The model was what was wrong, not the server.
+ *
+ * ── The rule ─────────────────────────────────────────────────────────────────
+ * The kernel names its refusals: an error that carries a string `code` and an object `params`. The
+ * kernel cannot reach the shell, so the host turns that into a shell `Refusal` here, adding which twin
+ * it was. The sentence is made where the reader's language is known (`SpeakRefusals`, or the import
+ * result's `refusal()`), under `error.<code>`. Anything without a name passes through untouched.
+ */
+function asModelRefusal(error, instanceId) {
+    if (error instanceof shell_1.Refusal)
+        return error;
+    const e = error;
+    if (!e || typeof e.code !== 'string' || !e.code || !e.params || typeof e.params !== 'object')
+        return error;
+    return new shell_1.Refusal(e.code, { ...e.params, instanceId }, String(e.message ?? e.code));
+}
+/** Run a step that loads or replays a model; a kernel refusal comes out as a `Refusal`. */
+function refusingModel(instanceId, step) {
+    try {
+        return step();
+    }
+    catch (error) {
+        throw asModelRefusal(error, instanceId);
+    }
+}
+//# sourceMappingURL=model-refusal.js.map

package/dist-server/engine/model-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-refusal.js","sourceRoot":"","sources":["../../server/engine/model-refusal.ts"],"names":[],"mappings":";;AAgBA,wCAKC;AAGD,sCAMC;AA9BD,iDAA+C;AAE/C;;;;;;;;;;;;;GAaG;AACH,SAAgB,cAAc,CAAC,KAAc,EAAE,UAAkB;IAC/D,IAAI,KAAK,YAAY,eAAO;QAAE,OAAO,KAAK,CAAA;IAC1C,MAAM,CAAC,GAAG,KAAuE,CAAA;IACjF,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC1G,OAAO,IAAI,eAAO,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,GAAI,CAAC,CAAC,MAA8B,EAAE,UAAU,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;AAC/G,CAAC;AAED,2FAA2F;AAC3F,SAAgB,aAAa,CAAI,UAAkB,EAAE,IAAa;IAChE,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IACzC,CAAC;AACH,CAAC","sourcesContent":["import { Refusal } from '@things-factory/shell'\n\n/*\n * **A twin model the kernel refuses is said by name** (ADR-0054).\n *\n * ── What went wrong (2026-10-10) ─────────────────────────────────────────────\n * The MES kernel refuses a model without a production declaration. The engine let that error through\n * as it was, so `twinReplay(miratek)` reached the screen as INTERNAL_SERVER_ERROR with the kernel's\n * English sentence in the shell's notice. The model was what was wrong, not the server.\n *\n * ── The rule ─────────────────────────────────────────────────────────────────\n * The kernel names its refusals: an error that carries a string `code` and an object `params`. The\n * kernel cannot reach the shell, so the host turns that into a shell `Refusal` here, adding which twin\n * it was. The sentence is made where the reader's language is known (`SpeakRefusals`, or the import\n * result's `refusal()`), under `error.<code>`. Anything without a name passes through untouched.\n */\nexport function asModelRefusal(error: unknown, instanceId: string): unknown {\n  if (error instanceof Refusal) return error\n  const e = error as { code?: unknown; params?: unknown; message?: unknown } | null\n  if (!e || typeof e.code !== 'string' || !e.code || !e.params || typeof e.params !== 'object') return error\n  return new Refusal(e.code, { ...(e.params as Record<string, any>), instanceId }, String(e.message ?? e.code))\n}\n\n/** Run a step that loads or replays a model; a kernel refusal comes out as a `Refusal`. */\nexport function refusingModel<T>(instanceId: string, step: () => T): T {\n  try {\n    return step()\n  } catch (error) {\n    throw asModelRefusal(error, instanceId)\n  }\n}\n"]}

package/dist-server/engine/twin-engine.js

@@ -24,6 +24,7 @@ const local_declarations_js_1 = require("./local-declarations.js");
 const runtime_key_js_1 = require("./runtime-key.js");
 const twin_state_channel_js_1 = require("./twin-state-channel.js");
 const producer_guard_js_1 = require("./producer-guard.js");
+const model_refusal_js_1 = require("./model-refusal.js");
 const command_routing_js_1 = require("./command-routing.js");
 const twin_instance_js_1 = require("../service/twin-instance/twin-instance.js");
 /* 자극의 집은 원본이다(ADR-0029) — 그 행을 읽고 쓴다. */
@@ -1387,7 +1388,7 @@ class TwinEngine {
         const Kernel = kernelFor(kind);
         const kernel = new Kernel(domainId, undefined, this.productionSpecOf(model));
         kernel.scopeId = id;
-        kernel.loadTwinModel(model); // 구조만. 상태는 아래 웜스타트가 주입한다.
+        (0, model_refusal_js_1.refusingModel)(id, () => kernel.loadTwinModel(model)); // 구조만. 상태는 아래 웜스타트가 주입한다.
         this.applyOperations(kernel, model, id); // 시간·수율 명세(있으면) — 없으면 커널 기본값
         /* 추정기는 DB 조회를 포함해 비동기 — 기동을 막지 않고 붙는다(붙기 전 작업은 명세·상수로 산출). */
         this.installEstimators(kernel, domainId, id, model).catch(err => (0, log_js_1.twinWarn)('[twin-engine] estimator install failed', err?.message));
@@ -1597,7 +1598,7 @@ class TwinEngine {
         const Kernel = kernelFor(kind);
         const kernel = new Kernel(domainId, undefined, this.productionSpecOf(model));
         kernel.scopeId = id;
-        kernel.loadTwinModel(model);
+        (0, model_refusal_js_1.refusingModel)(id, () => kernel.loadTwinModel(model));
         /* **세우는 쪽이 아는 사실은 세울 때 말한다.** 예전에는 첫 이벤트가 도착해야 커널이 스스로를
            관측 구동으로 여겼고, 그래서 아직 아무것도 못 받은 미러는 시뮬레이션 취급을 받았다. */
         declareObserved(kernel, `live twin '${id}'`);
@@ -3703,20 +3704,20 @@ class TwinEngine {
          */
         if (resume?.fold?.reducer && segments.length <= 1) {
             const model = (segments[0]?.model ?? (asOfNow && newest) ?? reg.model);
-            const out = replayFrom(model, resume.fold.reducer, segments[0]?.events ?? [], replayOptions(reg, domainId));
+            const out = (0, model_refusal_js_1.refusingModel)(instanceId, () => replayFrom(model, resume.fold.reducer, segments[0]?.events ?? [], replayOptions(reg, domainId)));
             return keep(withNow(out.state), { reducer: out.checkpoint, oee: oee.serialize() });
         }
         if (!segments.length) {
             const model = ((asOfNow && newest) || reg.model);
-            const out = replayWithCheckpoint(model, [], replayOptions(reg, domainId));
+            const out = (0, model_refusal_js_1.refusingModel)(instanceId, () => replayWithCheckpoint(model, [], replayOptions(reg, domainId)));
             return keep(withNow(out.state), { reducer: out.checkpoint, oee: oee.serialize() });
         }
         if (segments.length === 1) {
-            const out = replayWithCheckpoint(segments[0].model, segments[0].events, replayOptions(reg, domainId));
+            const out = (0, model_refusal_js_1.refusingModel)(instanceId, () => replayWithCheckpoint(segments[0].model, segments[0].events, replayOptions(reg, domainId)));
             return keep(withNow(out.state), { reducer: out.checkpoint, oee: oee.serialize() });
         }
         /* 커널 계약도 `model` 이다(0.6.14) — 경계에서 어휘를 되돌려 담던 브릿지가 사라졌다. */
-        const { state, shifts } = replaySegments(segments, replayOptions(reg, domainId));
+        const { state, shifts } = (0, model_refusal_js_1.refusingModel)(instanceId, () => replaySegments(segments, replayOptions(reg, domainId)));
         /* 경계에서 사라진 것을 알리지 않고 넘기지 않는다 — 수가 줄어든 이유를 어딘가에는 남겨야 한다. */
         for (const sh of shifts)
             if (sh.equipmentDropped || sh.locationsDropped || sh.personsDropped || sh.assetsDropped)
@@ -4515,7 +4516,7 @@ class TwinEngine {
             return null;
         const Kernel = kernelFor(reg.kind);
         const k = new Kernel(domainId, undefined, this.productionSpecOf(reg.model));
-        k.loadTwinModel(reg.model);
+        (0, model_refusal_js_1.refusingModel)(instanceId, () => k.loadTwinModel(reg.model));
         this.applyOperations(k, reg.model, instanceId); // 예측도 같은 명세로 굴러야 한다(화면과 다른 숫자 금지)
         await this.installEstimators(k, domainId, instanceId, reg.model); // 예측은 기다린다 — 실측을 놓치면 예측이 상수로 계산된다
         const state = await this.recover(domainId, instanceId, undefined, untilTime).catch(() => null);