@things-factory/headless-twin 10.0.11 → 10.0.12

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

@@ -8,7 +8,7 @@
  * (설계 SoT: operato-twin/design/integration/things-factory-host.md)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TwinEngine = exports.DEFAULT_REALITY_MODE = void 0;
+exports.TwinEngine = void 0;
 const shell_1 = require("@things-factory/shell");
 /* 저널을 자를 조건은 SQL 이 안다 — 관용구만 쓴다(원시 SQL 은 5개 드라이버에서 갈라진다). */
 const typeorm_1 = require("typeorm");
@@ -20,6 +20,8 @@ const local_declarations_js_1 = require("./local-declarations.js");
 const runtime_key_js_1 = require("./runtime-key.js");
 const command_routing_js_1 = require("./command-routing.js");
 const twin_instance_js_1 = require("../service/twin-instance/twin-instance.js");
+/* 자극의 집은 원본이다(ADR-0029) — 그 행을 읽고 쓴다. */
+const twin_reference_js_1 = require("../service/reference/twin-reference.js");
 const twin_structure_js_1 = require("../service/twin-structure/twin-structure.js");
 const twin_space_js_1 = require("../service/twin-space/twin-space.js");
 const reference_master_js_1 = require("../service/reference/reference-master.js");
@@ -32,6 +34,9 @@ const reference_master_js_3 = require("../service/reference/reference-master.js"
 const project_structure_js_1 = require("../service/twin-model/project-structure.js");
 const travel_estimator_js_1 = require("./travel-estimator.js");
 const measured_estimator_js_1 = require("./measured-estimator.js");
+const measured_yield_js_1 = require("./measured-yield.js");
+const declared_stimulus_js_1 = require("./declared-stimulus.js");
+const restart_policy_js_1 = require("./restart-policy.js");
 const kpi_query_js_1 = require("./kpi-query.js");
 const node_crypto_1 = require("node:crypto");
 const entity_delta_js_1 = require("@things-factory/headless-twin/dist-shared/entity-delta.js");
@@ -43,7 +48,7 @@ const attention_digest_js_1 = require("./attention-digest.js");
 const live_feed_registry_js_1 = require("./live-feed-registry.js");
 const twin_kernel_1 = require("@operato/twin-kernel");
 /* 커널 런타임 로드 — CJS 번들(dist-cjs). 타입은 위 import type 로. replay = 이벤트열→상태 재구성(복구·시간여행). */
-const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments, readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT } = require('@operato/twin-kernel');
+const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments, readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT, validateScenario } = require('@operato/twin-kernel');
 const KERNELS = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel, ems: EmsKernel };
 /**
  * 종류 문자열 → 커널. **모르는 값이면 던진다.**
@@ -61,7 +66,6 @@ function kernelFor(kind) {
         throw new Error(`unknown twin kind "${kind}" — expected one of ${Object.keys(KERNELS).join(' | ')}`);
     return K;
 }
-exports.DEFAULT_REALITY_MODE = 'sim-experiment';
 class TwinEngine {
     /*
      * 기동 중인 런타임 — **키는 `runtimeKey(domainId, instanceId)`** 다(`runtime-key.ts` 에 이유).
@@ -301,7 +305,7 @@ class TwinEngine {
      *
      * ── 모드를 지어내지 않는다 ──────────────────────────────────────────────────
      * 미러였던 트윈을 시뮬로 되살리면 **없던 움직임을 만들어 낸다**(관측 트윈이 스스로 물건을 옮긴다).
-     * 그래서 선언된 `realityMode` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
+     * 그래서 선언된 `restartPolicy` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
      *
      * ── 되살릴 수 없으면 그렇게 적는다 ──────────────────────────────────────────
      * 실패를 삼키면 등록부가 계속 `running` 이라 말한다 — 우리가 고치려던 그 거짓말이다. 그래서 실패한
@@ -323,7 +327,7 @@ class TwinEngine {
             return;
         }
         try {
-            if (row.realityMode === 'mirror') {
+            if (row.restartPolicy === 'resync') {
                 if (!row.model)
                     throw new Error('no model');
                 /* 시각 기준은 **공간**이 갖는다 — 교대의 HH:MM 을 어느 기준으로 읽나(라이브 기동과 같은 규칙). */
@@ -334,7 +338,7 @@ class TwinEngine {
             }
             else {
                 await this.startFromRegistry(domainId, instanceId);
-                console.log(`[twin-engine] resumed ${row.realityMode} "${instanceId}".`);
+                console.log(`[twin-engine] resumed ${row.restartPolicy} "${instanceId}".`);
             }
         }
         catch (err) {
@@ -445,6 +449,22 @@ class TwinEngine {
                 }
             }
         }
+        /* 공정 모수(수율·셋업)도 같은 규율로 싣는다 — 커널이 그 창구를 갖지 않으면 그 사실을 말한다. */
+        const params = model?.localParams;
+        if (params && Object.keys(params).length) {
+            if (typeof kernel?.declareParameters !== 'function') {
+                console.warn(`[twin-engine] "${id}": this facility declared operation parameters for ${Object.keys(params).length} operation(s) but the kernel cannot consume them ` +
+                    '(declareParameters missing — kernel needs publishing). Yield and setup keep running on built-in constants.');
+            }
+            else {
+                try {
+                    kernel.declareParameters(params);
+                }
+                catch (err) {
+                    console.warn(`[twin-engine] "${id}": declared operation parameter rejected by the kernel — ${err?.message ?? err}`);
+                }
+            }
+        }
         const ops = model?.operations;
         if (!ops?.length)
             return;
@@ -479,6 +499,31 @@ class TwinEngine {
             return;
         }
         kernel.durationEstimator = chained;
+        /*
+         * **양품률도 이력에서 배운다** (2026-08-19) — 소요와 같은 자리에서 붙인다.
+         *
+         * 커널이 그 시임을 갖지 않은 버전이면(발행 이전) 조용히 넘어가지 않고 말한다: 수율이 상수로 남은
+         * 이유를 모르고 지나가면, 화면의 불량 판정이 그 현장의 사실이 아니라 우리 상수의 결과다.
+         */
+        const yields = await this.measuredYield(domainId, instanceId);
+        if (yields?.estimator) {
+            if (typeof kernel.yieldOf !== 'function') {
+                console.warn(`[twin-engine] "${instanceId}": learned yield for ${Object.keys(yields.learned).length} operation kind(s) but the kernel cannot consume it ` +
+                    '(yieldOf missing — kernel needs publishing). Yield keeps running on the declared value or the built-in constant.');
+            }
+            else {
+                kernel.yieldEstimator = yields.estimator;
+                console.log(`[twin-engine] "${instanceId}": measured yield installed — ${Object.entries(yields.learned)
+                    .map(([k, v]) => `${k}=${Math.round(v * 1000) / 10}%(${yields.samples[k].good + yields.samples[k].scrap}건)`)
+                    .join(', ')}${yields.skipped.length ? ` · 표본 부족으로 뺀 종류: ${yields.skipped.map(s => `${s.kind}(${s.judged})`).join(', ')}` : ''}`);
+            }
+        }
+        else if (yields?.skipped.length) {
+            /* 배운 것이 없고 버린 것만 있으면 그 사실도 말한다 — 「이력이 없다」와 「표본이 모자라다」는 다르다. */
+            console.log(`[twin-engine] "${instanceId}": no measured yield yet — samples below ${yields.minSamples}: ${yields.skipped
+                .map(s => `${s.kind}(${s.judged})`)
+                .join(', ')}`);
+        }
         const learned = Object.keys(measured?.learned ?? {});
         const spread = Object.keys(measured?.spreads ?? {});
         console.log(`[twin-engine] "${instanceId}": duration estimator installed — measured kinds: ${learned.length ? learned.join(',') : 'none'}` +
@@ -508,6 +553,11 @@ class TwinEngine {
      * 정상 규모에서 서로 밀어내며 캐시가 무의미해진다(그게 더 나쁘다: 조용히 느려진다).
      */
     static { this.MEASURED_MAX = 5_000; }
+    /** 이 트윈이 이력에서 배운 양품률 — 소요와 **같은 폴드·같은 캐시**에서 온다(저널을 두 번 접지 않는다). */
+    static async measuredYield(domainId, instanceId) {
+        await this.measuredEstimator(domainId, instanceId);
+        return this.measuredCache.get((0, runtime_key_js_1.runtimeKey)(domainId, instanceId))?.yields;
+    }
     static async measuredEstimator(domainId, instanceId) {
         /* 키는 `runtimeKey` 하나로 — 손으로 조립하면 지우는 쪽과 어긋나 못 지우는 항목이 생긴다. */
         const key = (0, runtime_key_js_1.runtimeKey)(domainId, instanceId);
@@ -515,17 +565,20 @@ class TwinEngine {
         if (hit && Date.now() - hit.at < this.MEASURED_TTL_MS)
             return hit.value;
         let value;
+        let yields;
         try {
             /* 작업 종류별 실측 — 창은 넉넉히(하루) 두고 표본이 모자란 종류는 추정기가 스스로 뺀다. */
             const kpi = await (0, kpi_query_js_1.computeTwinKpi)({ domainId, instanceId, windowMinutes: 24 * 60, groupBy: 'taskKind' });
             value = (0, measured_estimator_js_1.buildMeasuredEstimator)(kpi?.groups?.items, {});
+            /* 같은 그룹에서 양품률도 배운다 — 한 번 접은 저널을 둘이 나눠 쓴다. */
+            yields = (0, measured_yield_js_1.buildYieldEstimator)(kpi?.groups?.items, {});
         }
         catch (err) {
             console.warn(`[twin-engine] "${instanceId}": measured duration lookup failed — falling back to declared/default durations.`, err?.message);
         }
         /* 다시 넣어 **최근 쓴 것**으로 만든다 — 삽입 순서가 곧 버릴 순서이므로 이 한 줄이 LRU 를 만든다. */
         this.measuredCache.delete(key);
-        this.measuredCache.set(key, { at: Date.now(), value });
+        this.measuredCache.set(key, { at: Date.now(), value, yields });
         if (this.measuredCache.size > this.MEASURED_MAX) {
             const oldest = this.measuredCache.keys().next();
             if (!oldest.done)
@@ -533,6 +586,66 @@ class TwinEngine {
         }
         return value;
     }
+    /**
+     * **원본이 선언한 자극을 싣는다** — 재기동해도 살아 있게 (2026-08-19).
+     *
+     * ── 무엇이 났나 ────────────────────────────────────────────────────────────
+     * 데모의 시나리오는 시드 코드가 메모리에만 실었다. 그래서 트윈을 재기동하면 자극이 사라지고 구조만
+     * 서 있는 트윈이 남았다(작업 0·오더 0) — 「살아 있는 데모」가 **첫 재기동까지만** 살았다.
+     *
+     * 자극의 집은 **원본**이다(`TwinReference.connectionConfig.scenario`, ADR-0029 ·
+     * `plans/simulator-as-source.md` §4): 무엇이 들어오고 무슨 주문이 나는지는 시뮬레이터가 정하는 사실이고
+     * 트윈은 반영한다. 트윈에 새 축을 만들면 ADR-0029 가 걷어내야 할 표면이 하나 늘어난다.
+     *
+     * 판정은 순수 함수가 한다(`planStimulus`) — 미러에 싣지 않고, 검사를 통과하지 못한 선언은 태우지 않고
+     * (그 이력이 있다: 잘못된 선언 하나가 다음 틱에서 서버를 내렸다), 못 실은 이유는 **말한다.**
+     */
+    static async installStimulus(domainId, instanceId, inst) {
+        let config;
+        try {
+            const ref = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } });
+            config = ref?.connectionConfig;
+        }
+        catch (err) {
+            console.warn(`[twin-engine] "${instanceId}": could not read the declared stimulus — ${err?.message ?? err}`);
+            return;
+        }
+        const plan = (0, declared_stimulus_js_1.planStimulus)(config, { hasScenarioEngine: !!inst.runtime?.scenario, mode: inst.mode }, validateScenario);
+        if (plan.action === 'skip') {
+            /* 선언이 없는 것은 정상이므로 조용히 지난다. 나머지 셋은 **말한다** — 선언했는데 안 실린 상태다. */
+            if (plan.reason !== 'none') {
+                console.warn(`[twin-engine] "${instanceId}": a stimulus is declared on its source but was not loaded (${plan.reason}${plan.detail ? `: ${plan.detail}` : ''}).` +
+                    (plan.reason === 'observed' ? ' This twin runs on observation — we do not manufacture arrivals for it.' : ''));
+            }
+            return;
+        }
+        try {
+            inst.runtime.scenario.load(plan.scenario);
+            inst.runtime.scenario.start();
+            const kinds = (plan.scenario.generators ?? []).map((g) => g?.kind).filter(Boolean);
+            console.log(`[twin-engine] "${instanceId}": stimulus from its source started — ${kinds.length ? kinds.join(', ') : 'no generators'}.`);
+        }
+        catch (err) {
+            console.warn(`[twin-engine] "${instanceId}": the declared stimulus was rejected at load — ${err?.message ?? err}`);
+        }
+    }
+    /**
+     * 자극을 **원본에 선언한다** — 프로비저닝·데모 시드가 부르는 문.
+     *
+     * 트윈이 아니라 원본에 적는 이유는 위와 같다(ADR-0029). 원본 행이 없으면 만들지 않는다 — 어떤 원본에서
+     * 온 트윈인지 모르는 채 자극을 지어 붙이면, 그 자극이 어디서 왔는지 아무도 되짚을 수 없다.
+     */
+    static async declareStimulus(domainId, instanceId, scenario) {
+        const repo = (0, shell_1.getRepository)(twin_reference_js_1.TwinReference);
+        const ref = await repo.findOne({ where: { domain: { id: domainId }, source: instanceId } });
+        if (!ref) {
+            console.warn(`[twin-engine] "${instanceId}": no source reference — a stimulus has nowhere to be declared.`);
+            return false;
+        }
+        ref.connectionConfig = (0, declared_stimulus_js_1.withStimulus)(ref.connectionConfig, scenario);
+        await repo.save(ref);
+        return true;
+    }
     /**
      * 이 트윈이 **이력에서 시간을 배운 작업 종류들** — 재기동에도 남는 근거.
      *
@@ -656,7 +769,7 @@ class TwinEngine {
         ].join(', ');
         console.log(`[twin-engine] mirror "${id}" carried over ${carried} — observation axes come from the source.`);
     }
-    static start(id, domainId, kind, model, realityMode, purpose, resumeFrom) {
+    static start(id, domainId, kind, model, restartPolicy, purpose, resumeFrom) {
         const key = (0, runtime_key_js_1.runtimeKey)(domainId, id);
         if (this.instances[key])
             return this.instances[key];
@@ -695,11 +808,23 @@ class TwinEngine {
          * 실제로는 도는 커널이 옛 수를 그대로 쓰고 재기동 때 받는데, 그 사실이 답에서 사라진 것이다.
          * 규약에 기대는 대신 사실을 적는다: 「돌고 있나」를 묻는 쪽이 그 답을 받아야 한다.
          */
-        const inst = { id, domainId, mode: 'sim', runtime, kernel, realityMode: realityMode ?? exports.DEFAULT_REALITY_MODE, spaceId: model?.spaceId, unsub: () => { } };
+        const inst = {
+            id,
+            domainId,
+            mode: 'sim',
+            runtime,
+            kernel,
+            /* 정책은 부르는 쪽이 선언한다 — 여기서 고르면 같은 트윈이 부르는 자리에 따라 다르게 재기동한다. */
+            restartPolicy: (0, restart_policy_js_1.readRestartPolicy)(restartPolicy, `start("${id}")`),
+            spaceId: model?.spaceId,
+            unsub: () => { }
+        };
         this.instances[key] = inst;
         /* 다시 세웠으므로 지난 정지 이유는 사실이 아니다 — 남겨 두면 도는 트윈이 「굶겨서 멈췄다」고 말한다. */
         this.stopNotes.delete(key);
         delete this.recovered[key]; // 웜스타트로 커널에 옮겨 심었다 — 이제 라이브가 진실이다.
+        /* 원본이 선언한 자극 — 기동을 막지 않는다(추정기와 같은 규율). 못 실었으면 그 사실을 말한다. */
+        this.installStimulus(domainId, id, inst).catch(err => console.warn(`[twin-engine] "${id}": stimulus install failed — ${err?.message ?? err}`));
         /* 라이브 바인딩(P3): data 채널 필터가 subdomain 을 보므로 Domain 객체를 1회 해석해 둔다. */
         (0, shell_1.getRepository)(shell_1.Domain).findOne({ where: { id: domainId } }).then(d => (inst.domain = d)).catch(() => { });
         /* State 채널: runtime.subscribe(snapshot→delta→clock) → pubsub 방송(구독 리졸버가 instanceId 필터). */
@@ -725,8 +850,8 @@ class TwinEngine {
             }
         });
         inst.unsub = () => sub.unsubscribe();
-        /* 복구 앵커: 레지스트리에 model/kind/status/realityMode 영속(재부팅 시 이게 있어야 replay·선언 거동 가능). */
-        this.register(domainId, id, kind, model, 'running', inst.realityMode).catch(err => console.error('twin register fail', err));
+        /* 복구 앵커: 레지스트리에 model/kind/status/restartPolicy 영속(재부팅 시 이게 있어야 replay·선언 거동 가능). */
+        this.register(domainId, id, kind, model, 'running', inst.restartPolicy).catch(err => console.error('twin register fail', err));
         /* 워커 tick — 스켈레톤은 setInterval(메인 루프). 긴 시뮬 오프-루프(worker thread)는 스케일 하드닝(향후, §host 경계). */
         inst.timer = setInterval(() => this.tickGuarded(domainId, id, runtime), this.TICK_MS);
         return inst;
@@ -809,7 +934,7 @@ class TwinEngine {
         /* `projector` 필드는 옛 이름으로 남긴다 — 소비처가 `snapshot()` 을 부르므로 얇은 어댑터로 잇는다.
          * (P3 에서 소비처를 커널 어휘로 바꾸면 사라진다.) */
         const projector = { apply: (e) => kernel.apply(e), snapshot: () => kernel.getSnapshot() };
-        const inst = { id, domainId, mode: 'live', realityMode: 'mirror', kernel, projector, oee: new oee_accumulator_js_1.OeeAccumulator(), spaceId: model?.spaceId, unsub: () => { } };
+        const inst = { id, domainId, mode: 'live', restartPolicy: 'resync', kernel, projector, oee: new oee_accumulator_js_1.OeeAccumulator(), spaceId: model?.spaceId, unsub: () => { } };
         /*
          * ── 커널이 **판정으로 낸 사실**도 저널에 남는다 (2026-08-14 실측으로 잡음) ────
          *
@@ -839,6 +964,8 @@ class TwinEngine {
         this.installEstimators(kernel, domainId, id, model).catch(err => console.warn('[twin-engine] estimator install failed', err?.message));
         inst.metrics = { ingestedTotal: 0, broadcastTotal: 0, journaledTotal: 0, ingestRate: 0, broadcastRate: 0, journalRate: 0, backlog: 0, _accIngest: 0, _accBroadcast: 0, _accJournal: 0, _windowStartMs: Date.now() };
         this.instances[key] = inst;
+        /* 미러에도 부른다 — 선언이 있으면 「미러에는 싣지 않는다」고 말해야 한다(조용한 무시 금지). */
+        this.installStimulus(domainId, id, inst).catch(err => console.warn(`[twin-engine] "${id}": stimulus check failed — ${err?.message ?? err}`));
         /*
          * **원천이 되풀어 주지 않는 것만 잇는다** (2026-08-18 실측으로 붙임).
          *
@@ -859,7 +986,7 @@ class TwinEngine {
             .findOne({ where: { domain: { id: domainId }, instanceId: id }, order: { revision: 'DESC' } })
             .then(top => (inst.revision = top?.revision ?? 0))
             .catch(() => (inst.revision = 0));
-        this.register(domainId, id, kind, model, 'running', 'mirror').catch(err => console.error('twin register fail', err));
+        this.register(domainId, id, kind, model, 'running', 'resync').catch(err => console.error('twin register fail', err));
         return inst;
     }
     /**
@@ -1034,7 +1161,7 @@ class TwinEngine {
         await repo.save(rows, { chunk: 500 });
     }
     /** 레지스트리 upsert(도메인+instanceId 유니크). status 인자로 provision(stopped)/start(running) 공용. */
-    static async register(domainId, instanceId, kind, model, status = 'running', realityMode, origin, 
+    static async register(domainId, instanceId, kind, model, status = 'running', restartPolicy, origin, 
     /*
      * 사람이 부르는 이름과 **누가 했나** — 업무키를 나눠 둔 대가로 이름을 함께 실어야 한다.
      * 사람 없는 경로(부팅 자동 프로비저닝·복구)는 `actor` 를 주지 않는다 — 아무 사용자를 적으면
@@ -1052,10 +1179,11 @@ class TwinEngine {
             // 인스턴스↔공간 1급 링크(space #3) — model.spaceId/areaId 를 컬럼으로 승격(dual-write). model JSON 도 유지(커널·복구용).
             spaceId: model?.spaceId ?? existing?.spaceId,
             areaId: model?.areaId ?? existing?.areaId,
-            /* 현실 출처 선언(§0 ①) — 명시값 우선, 없으면 기존값 보존(재프로비전이 선언을 지우지 않게).
-               둘 다 없으면 여기서 **각인한다**. 컬럼을 비워 두면 읽는 자리마다 기본값을 고르게 되고,
-               그러면 같은 트윈이 부르는 곳에 따라 다르게 재기동한다. 선언은 저장소에서 항상 명시적이다. */
-            realityMode: realityMode ?? existing?.realityMode ?? exports.DEFAULT_REALITY_MODE,
+            /* 재기동 정책(ADR-0029 §2) — 명시값 우선, 없으면 기존값 보존(재프로비전이 선언을 지우지 않게).
+               **둘 다 없으면 던진다**: 예전에는 여기서 기본값을 각인했는데, 그 기본값이 「저널 초기화」라서
+               선언을 빠뜨린 프로비저닝이 조용히 이력을 지우는 트윈을 만들었다. 선언은 부르는 쪽의 몫이다. */
+            restartPolicy: restartPolicy ??
+                (0, restart_policy_js_1.readRestartPolicy)(existing?.restartPolicy, `register("${instanceId}") did not declare a restart policy and the stored row has none`),
             /* 용도도 각인한다. 벤치로 뒤집는 것은 `setPurpose` 하나뿐이므로 기존값을 반드시 보존한다
                — 여기서 덮으면 재프로비전이 벤치 사본을 운영 트윈으로 되돌린다. */
             purpose: existing?.purpose ?? 'operational',
@@ -1186,7 +1314,15 @@ class TwinEngine {
         this.ensureBroadcastCoalescer();
         return { rev, ...shift };
     }
-    static async provision(domainId, instanceId, kind, model, comment, origin, 
+    static async provision(domainId, instanceId, kind, model, 
+    /**
+     * **재기동 정책은 생성 시점의 선언이다**(ADR-0029 §2) — 트윈은 정책 없이 존재할 수 없다.
+     *
+     * 예전에는 이 자리가 없었고 `register` 가 기본값(`sim-experiment` = 저널 초기화)을 각인했다. 그래서
+     * 선언을 빠뜨린 프로비저닝이 **재기동마다 이력을 지우는 트윈**을 조용히 만들었다. 이제 만드는 쪽이
+     * 말해야 한다: 이 트윈이 자기 과거를 어떻게 대하는지는 만드는 사람이 아는 사실이다.
+     */
+    restartPolicy, comment, origin, 
     /** 이름·저자 — 업무키를 나눠 둔 대가로 이름을 함께 남긴다(`register` 의 `meta` 그대로). */
     meta) {
         this.assertNotRunning(domainId, instanceId);
@@ -1207,7 +1343,7 @@ class TwinEngine {
          * 달고 다닌다. 재생은 구조가 바뀌는 지점에서 전환한 뒤 이어 접는다(`replaySegments`).
          */
         await this.recordStructure(domainId, instanceId, model, comment);
-        await this.register(domainId, instanceId, kind, model, existing?.status === 'running' ? 'stopped' : existing?.status ?? 'stopped', undefined, origin, meta);
+        await this.register(domainId, instanceId, kind, model, existing?.status === 'running' ? 'stopped' : existing?.status ?? 'stopped', restartPolicy, origin, meta);
     }
     /**
      * 이 구조를 리비전으로 남기고 그 번호를 돌려준다 — **바뀌었을 때만** 새 번호가 생긴다.
@@ -1308,7 +1444,7 @@ class TwinEngine {
         return `N[${locations}]M[${equipment}]`;
     }
     /** 레지스트리 model 로 기동(프로비전된 인스턴스 start). model 인자 없이 저장된 구조로 재기동. */
-    static async startFromRegistry(domainId, instanceId, realityMode) {
+    static async startFromRegistry(domainId, instanceId, restartPolicy) {
         const key = (0, runtime_key_js_1.runtimeKey)(domainId, instanceId);
         if (this.instances[key])
             return this.instances[key];
@@ -1336,7 +1472,7 @@ class TwinEngine {
         /*
          * 저널에 남아 있는 마지막 번호 — **모드와 무관하게** 이것을 이어 센다.
          *
-         * 저널을 초기화하고 기동하는 모드(sim-experiment)라면 이 값이 0이라 아무 영향이 없다. 규칙을
+         * 저널을 초기화하고 기동하는 정책(`reset`)이라면 이 값이 0이라 아무 영향이 없다. 규칙을
          * 모드별로 구분하지 않는 이유: "저널이 비어 있지 않으면 그 뒤부터" 하나면 어느 모드에서도
          * 겹칠 수 없고, 모드가 늘어도 이 자리를 다시 손볼 일이 없다.
          */
@@ -1349,26 +1485,28 @@ class TwinEngine {
         return this.start(instanceId, domainId, 
         /* 커널 종류·현실 선언은 레지스트리에 반드시 있다(둘 다 NOT NULL). 예전에는 `?? 'wms'` 로
            메웠는데, 그건 YMS/MES 트윈을 **조용히 WMS 로 부팅**시키는 길이었다 — 오류 없이 다른 공장이 뜬다. */
-        reg.kind, reg.model, realityMode ?? reg.realityMode, reg.purpose, Number(last?.max ?? 0) || 0);
+        reg.kind, reg.model, 
+        /* 저장된 값은 **엄격히** 읽는다 — 모르는 값을 기본값으로 메우면 그 트윈이 조용히 다르게 재기동한다. */
+        restartPolicy ?? (0, restart_policy_js_1.readRestartPolicy)(reg.restartPolicy, `twin "${instanceId}"`), reg.purpose, Number(last?.max ?? 0) || 0);
     }
     /**
-     * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 realityMode 에 따라 재기동 방식을 구분한다.
+     * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 restartPolicy 에 따라 재기동 방식을 구분한다.
      * 부팅 경로를 한 곳에 모아 "런타임 ≠ 현실" 범주오류를 코드로 강제한다.
-     *   - 'mirror'         : 현실=외부 실물 → startLive(재동기). 이벤트는 어댑터 ingest 로 유입, 커널 tick 없음.
-     *   - 'sim-world'      : 생성 타임라인 지속 → 저널 보존 + resume(현실 이어감).
+     *   - 'resync'         : 현실=외부 실물 → startLive(재동기). 이벤트는 어댑터 ingest 로 유입, 커널 tick 없음.
+     *   - 'resume'      : 생성 타임라인 지속 → 저널 보존 + resume(현실 이어감).
      *                        ⚠ GATE(§8 ②③): 커널 상태 직렬화/재개가 아직 없어 진짜 resume 불가 → 실 필요·실부하 시 구현.
      *                        그때까지는 저널을 보존하되 revision 충돌을 피하려 fresh 로 기동하고, 선언과 구현의 간극을 크게 경고한다.
-     *   - 'sim-experiment' : seed 재현 → resetJournal + fresh 기동(백지 시작이 버그가 아니라 선언된 거동).
+     *   - 'reset' : seed 재현 → resetJournal + fresh 기동(백지 시작이 버그가 아니라 선언된 거동).
      * 반환: 기동된 InstanceRuntime.
      */
-    static async bootDeclared(domainId, instanceId, mode = exports.DEFAULT_REALITY_MODE) {
-        if (mode === 'mirror') {
+    static async bootDeclared(domainId, instanceId, mode) {
+        if (mode === 'resync') {
             const reg = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
             if (!reg?.model)
                 throw new Error(`instance "${instanceId}" not provisioned (no model)`);
             return this.startLive(instanceId, domainId, reg.kind, reg.model);
         }
-        if (mode === 'sim-world') {
+        if (mode === 'resume') {
             /*
              * **이어지는 현실** — 저널을 지우지 않는다.
              *
@@ -1381,11 +1519,11 @@ class TwinEngine {
              * 같은 씨앗에서 다시 시작하므로 자극의 패턴이 재기동 지점에서 한 번 끊긴다. 쌓인 사실과
              * 상태는 이어지고, 앞으로 일어날 일의 무작위 순서만 새로 시작한다.
              */
-            return this.startFromRegistry(domainId, instanceId, 'sim-world');
+            return this.startFromRegistry(domainId, instanceId, 'resume');
         }
-        // sim-experiment(기본): seed 재현 — 저널 초기화 후 revision 0 부터 재실행.
+        // `reset`: seed 재현 — 저널 초기화 후 revision 0 부터 재실행.
         await this.resetJournal(domainId, instanceId);
-        return this.startFromRegistry(domainId, instanceId, 'sim-experiment');
+        return this.startFromRegistry(domainId, instanceId, 'reset');
     }
     /**
      * 저널 초기화 — 인스턴스 이벤트 저널 purge(레지스트리·상태는 유지).
@@ -1471,7 +1609,7 @@ class TwinEngine {
                 spaceId: r.spaceId, // co-location: 같은 spaceId 인스턴스들이 한 현장 공유 — 현장뷰 집약 키(G7)
                 /* 사람이 읽는 현장 이름 — 없으면 `undefined`(화면이 "이름 없음" 을 알아볼 수 있어야 한다). */
                 spaceName: (r.spaceId ? spaceNameOf.get(r.spaceId) : undefined) || undefined,
-                realityMode: r.realityMode, // 현실 출처 선언(§0 ①) — mirror/sim-world/sim-experiment. 저장 시 각인되므로 비지 않는다.
+                restartPolicy: r.restartPolicy, // 재기동 정책(ADR-0029 §2) — resync/resume/reset. 선언이므로 비어 있을 수 없다.
                 purpose: r.purpose, // 운영 vs 벤치 사본(1급 구별 — 이름 접두사 아님). 저장 시 각인되므로 비지 않는다.
                 copyOf: r.copyOf ?? undefined,
                 running: !!this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, r.instanceId)],
@@ -1485,7 +1623,7 @@ class TwinEngine {
                 /* 스스로 멈춘 이유 — 있으면 낸다. 재기동 뒤에는 없다(그때는 「모른다」가 사실이다). */
                 stopNote: this.stopNotes.get((0, runtime_key_js_1.runtimeKey)(domainId, r.instanceId)) || undefined,
                 liveFeed: (0, live_feed_registry_js_1.liveFeedStateOf)({
-                    realityMode: r.realityMode,
+                    restartPolicy: r.restartPolicy,
                     running: !!this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, r.instanceId)],
                     instanceId: r.instanceId
                 }),
@@ -1567,7 +1705,9 @@ class TwinEngine {
      * 기존 공간으로 들어갈 수 있다. 아래 병합은 원래 그 경우를 위해 있었는데(N:1) 만드는 흐름에서
      * 공간을 고를 방법이 없었다 — 마스터가 파생한 id 만 쓰였다. 판정은 `resolveIngestSpace`(순수).
      */
-    static async ingestMaster(domainId, master, into, 
+    static async ingestMaster(domainId, master, 
+    /** 만들어지는 트윈의 재기동 정책 — 원본이 정하는 것이 아니라 **만드는 쪽의 선언**이다(ADR-0029 §2). */
+    restartPolicy, into, 
     /** 누가 인제스트했나 — 사람이 없는 경로(부팅)는 주지 않는다(감사 기록을 지어내지 않는다). */
     actor) {
         /*
@@ -1734,7 +1874,7 @@ class TwinEngine {
         }
         else {
             /* 사이트 이름이 곧 트윈의 이름이다 — 마스터가 이미 말했으므로 지어내지 않고 그대로 싣는다. */
-            await this.provision(domainId, master.source, master.system, model, undefined, master.origin, {
+            await this.provision(domainId, master.source, master.system, model, restartPolicy, undefined, master.origin, {
                 name: master.siteName,
                 description: master.description,
                 actor
@@ -1783,7 +1923,7 @@ class TwinEngine {
             kind: r.kind,
             status: r.status,
             running: !!this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, r.instanceId)],
-            realityMode: r.realityMode, // 현실 선언 — what-if 적용 가드용(mirror=예측 전용, 자극 주입 불가)
+            restartPolicy: r.restartPolicy, // 현실 선언 — what-if 적용 가드용(mirror=예측 전용, 자극 주입 불가)
             model: r.model
         };
     }
@@ -2453,7 +2593,7 @@ class TwinEngine {
             mode: inst.mode ?? 'sim',
             domainId: inst.domainId,
             domainLabel: inst.domain?.subdomain,
-            realityMode: inst.realityMode,
+            restartPolicy: inst.restartPolicy,
             tickMs: this.TICK_MS,
             running: !!inst.timer || inst.mode === 'live',
             ...((0, load_meter_js_1.loadSummary)(inst.load, this.TICK_MS) ?? { recent: null, total: null, forksCreated: 0, overBudget: 0, budgetMs: this.TICK_MS * 0.5, loadRatio: null })