@things-factory/headless-twin 10.0.11 → 10.0.12

package/server/service/reference/reference-adapter.ts

@@ -52,6 +52,56 @@ export interface AdapterMeta {
   docUrl?: string // grounding='vendor-doc' 의 근거 문서 URL(출처 추적)
 }
 
+/**
+ * 원본이 **선언하는 능력** — 「이 원본으로 무엇을 할 수 있나」 (ADR-0029 §8, 2026-08-19).
+ *
+ * ── 왜 능력으로 선언하나 ────────────────────────────────────────────────────
+ * 실 WMS 는 스스로 사실을 낸다. 시뮬레이터는 **구동해 줘야** 움직인다 — 자극·속도·정지·초기화. 그런데
+ * 계약에 그 자리가 없어서 통제가 `TwinEngine` 안에 뚫려 있었다(`controlTwinScenario` 가 런타임의 시나리오
+ * 엔진을 직접 잡았다). 그러면 ADR-0029 의 판정 문장(*"실물이 같은 계약으로 할 수 있는가"*)에 걸린다:
+ * 실 WMS 는 일시정지될 수 없으니 그 통제면은 영원히 「어댑터 규약의 결손」으로 남고, 규칙이 그 면을
+ * **숨게** 만든다.
+ *
+ * 그래서 뒤집는다: 통제는 **선언된 능력**이다. 선언하지 않은 원본에는 그 문이 **아예 열리지 않는다** —
+ * 그것이 결손이 아니라 **사실**이다(실 WMS 는 정지되지 않는다). 이 레포가 이미 그 규율로 굴러간다
+ * (`capability-contract`: concrete 강결합 대신 능력 선언).
+ *
+ *  · `live`    — 돌아가는 피드를 낸다(`openLiveFeed`).
+ *  · `control` — 구동을 받는다(`control`) — 자극·속도·정지·초기화.
+ */
+export type ReferenceCapability = 'live' | 'control'
+
+/** 원본에 보내는 구동 명령 — **시뮬레이터를 움직이는 말**이지 트윈을 고치는 말이 아니다. */
+export interface ControlCommand {
+  /**
+   *  · `stimulus` — 자극을 싣는다(`scenario`). 선언은 원본 설정에 살고 이 명령은 지금 태우는 것이다.
+   *  · `start`·`pause` — 구동을 켜고 멈춘다.
+   *  · `speed`    — 시각의 배속(`speed`).
+   *  · `reset`    — 씨앗부터 다시(원본의 상태를 되돌린다 — 트윈의 저널은 재기동 정책이 정한다).
+   */
+  action: 'stimulus' | 'start' | 'pause' | 'speed' | 'reset'
+  /** 자극 선언 — `action: 'stimulus'` 에만. 커널 규약(`validateScenario`)으로 검사된 값이어야 한다. */
+  scenario?: any
+  /** 배속 — `action: 'speed'` 에만. */
+  speed?: number
+  /**
+   * 어느 트윈을 위한 구동인가 — 원본이 여러 트윈에 먹일 수 있으므로 대상을 함께 말한다.
+   *
+   * 인프로세스 시뮬레이터는 이 둘로 자기 런타임을 찾는다(테넌트까지 있어야 같은 id 의 두 트윈이 갈린다).
+   * 원격 원본은 대개 무시한다(자기 세계가 하나다).
+   */
+  instanceId?: string
+  domainId?: string
+}
+
+/** 구동 결과 — **왜 안 됐는지**를 코드로 말한다(화면이 옮긴다). */
+export interface ControlResult {
+  ok: boolean
+  /** 언어중립 사유 — `not-declared`(능력 없음) · `unsupported-action` · `invalid`(선언 거절) · `no-target`. */
+  code?: string
+  detail?: string
+}
+
 export interface ReferenceAdapter {
   /** 레지스트리 키 (예: 'virtual' | 'sap-ewm' | 'custom-rest'). */
   type: string
@@ -65,6 +115,34 @@ export interface ReferenceAdapter {
   fetchMaster(cfg: ConnectionConfig, site: SiteDescriptor): Promise<ReferenceMaster>
   /** (선택) 사이트별 실 이벤트 스트림 — 없으면 sim. onRecords 로 레코드 push, unsubscribe 반환. */
   openLiveFeed?(cfg: ConnectionConfig, site: SiteDescriptor, onRecords: (records: unknown[]) => void): () => void
+  /**
+   * 이 원본이 **선언하는 능력** — 없으면 「구조만 준다」는 뜻이다(ADR-0029 §8).
+   *
+   * 선언과 구현이 어긋나지 않게 `capabilitiesOf` 가 둘을 함께 본다: `control` 을 선언했는데 `control`
+   * 구현이 없으면 그 능력은 **없는 것으로 읽는다**(선언만 있는 능력은 사용자에게 거짓말이 된다).
+   */
+  capabilities?: ReferenceCapability[]
+  /**
+   * (선택) 구동 — 자극·속도·정지·초기화. **`capabilities` 에 `control` 을 선언한 원본만** 가진다.
+   *
+   * 실 시스템은 이것을 갖지 않는다(실 WMS 는 일시정지되지 않는다). 그 사실이 결손이 아니라 이 축의 요점이다.
+   */
+  control?(cfg: ConnectionConfig, site: SiteDescriptor | undefined, command: ControlCommand): Promise<ControlResult>
+}
+
+/**
+ * 이 원본이 **실제로 할 수 있는 것** — 선언과 구현의 교집합.
+ *
+ * 선언만 있고 구현이 없으면 화면이 「할 수 있다」고 말한 뒤 아무 일도 일어나지 않는다. 반대로 구현이
+ * 있는데 선언이 없으면 그 능력은 **의도적으로 닫아 둔 것**이므로 열지 않는다 — 선언이 권위다.
+ */
+export function capabilitiesOf(adapter: ReferenceAdapter | undefined): ReferenceCapability[] {
+  if (!adapter) return []
+  const declared = new Set(adapter.capabilities ?? [])
+  const out: ReferenceCapability[] = []
+  if (declared.has('live') && typeof adapter.openLiveFeed === 'function') out.push('live')
+  if (declared.has('control') && typeof adapter.control === 'function') out.push('control')
+  return out
 }
 
 /* 어댑터 "타입" 레지스트리(전역·인메모리) — 레퍼런스 데이터는 DB(TwinReference), 어댑터 동작은 여기. */

package/server/service/reference/reference-live.ts

@@ -6,7 +6,7 @@ import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinReference } from './twin-reference.js'
 
 /*
- * 커넥터 기반 라이브 피드 결선(reference → live, §0 프레임 ① realityMode='mirror').
+ * 커넥터 기반 라이브 피드 결선(reference → live, §0 프레임 ① restartPolicy='resync').
  * 흐름: adapter.openLiveFeed(cfg, site, records) → ingestCanonicalRecords(정규→봉투) → TwinEngine.ingestLive(projector 미러).
  * 커넥터가 "벤더 이벤트 → 정규 레코드" 매핑을 소유(코드)한다 — preset 기반 startLiveFeed(operato-twin, http-get+jsonata)와
  * 대칭이되, 매핑 위치만 다르다. 실 시스템 전환은 connectionConfig.baseUrl 교체뿐(코드 경로 동일).
@@ -33,7 +33,7 @@ export async function startReferenceLiveFeed(
   const det = await TwinEngine.detail(domainId, instanceId)
   if (!det?.model) throw new Error(`instance "${instanceId}" not provisioned (no model) — ingest master before live start`)
 
-  // mirror 모드 기동 — 커널 tick 없이 projector 가 실 이벤트를 미러(startLive 가 realityMode='mirror' 설정).
+  // 관측 기동 — 커널 tick 없이 projector 가 실 이벤트를 반영한다(startLive 가 restartPolicy='resync' 로 적는다).
   // 시각 기준은 **공간**이 갖는다(테넌트 아님) — 교대의 HH:MM 을 어느 기준으로 읽나.
   TwinEngine.startLive(instanceId, domainId, det.kind, await TwinEngine.withSpaceTimeBase(det.model, domainId))
 
@@ -121,7 +121,7 @@ export async function resumeReferenceLiveFeeds(): Promise<{ resumed: string[]; f
         where: produced.map((p: any) => ({ domain: { id: domainId }, instanceId: p.instanceId })) as any
       })
       const live = produced.filter((p: any) =>
-        rows.some(r => r.instanceId === p.instanceId && r.status === 'running' && r.realityMode === 'mirror')
+        rows.some(r => r.instanceId === p.instanceId && r.status === 'running' && r.restartPolicy === 'resync')
       )
       if (!live.length) continue
 

package/server/service/reference/reference-resolver.ts

@@ -3,6 +3,7 @@ import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { readRestartPolicy } from '../../engine/restart-policy.js'
 import { readBoardEquipment } from '@operato/twin-kernel'
 
 import { applyKnobDefaults, filledKnobKeys } from './knob-defaults.js'
@@ -140,9 +141,13 @@ export class TwinReferenceResolver {
 
   /** 소스를 인제스트 → 공간 + 인스턴스 생성(provision). start 면 기동까지. */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, { description: 'Ingest a registered reference source into a twin (space + instance). Optionally start it.' })
+  @Mutation(returns => ScalarObject, {
+    description:
+      "Ingest a registered reference source into a twin (space + instance). Optionally start it. restartPolicy declares how the new twin treats its own past on reboot: 'resync' (read the source again) | 'resume' (continue its journal) | 'reset' (wipe and replay from the seed). It has no default — a twin cannot exist without the declaration."
+  })
   async importFromReference(
     @Arg('source') source: string,
+    @Arg('restartPolicy') restartPolicy: string,
     @Ctx() context: ResolverContext,
     @Arg('start', { nullable: true }) start?: boolean
   ): Promise<any> {
@@ -153,7 +158,13 @@ export class TwinReferenceResolver {
       /* 어디서 왔는지 남긴다 — 이것이 없으면 이 트윈은 두 번 다시 읽을 수 없다.
          이 경로는 **메모리에 등록된 마스터 하나**를 그대로 쓰므로 사이트 서술자가 없다(사이트 정체를
          적을 것이 없다). 다시 읽기도 같은 등록본을 집으므로 사이트를 찾을 필요가 없다. */
-      const res = await TwinEngine.ingestMaster(domainId, { ...master, origin: { kind: 'reference', source } }, undefined, context.state.user)
+      const res = await TwinEngine.ingestMaster(
+        domainId,
+        { ...master, origin: { kind: 'reference', source } },
+        readRestartPolicy(restartPolicy, 'importFromReference'),
+        undefined,
+        context.state.user
+      )
       if (start) await TwinEngine.startFromRegistry(domainId, res.instanceId)
       return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings: res.warnings }
     } catch (e: any) {
@@ -204,7 +215,14 @@ export class TwinReferenceResolver {
        * 기본 공간으로 옮겨 간다 — 조용히 현장을 떠나고 그 현장의 값도 잃는다).
        */
       const keepSpace = origin.spaceId || inst.spaceId
-      const res = await TwinEngine.ingestMaster(domainId, master, keepSpace ? { spaceId: keepSpace } : undefined, context.state.user)
+      /* 다시 읽기는 **구조만** 새로 그린다 — 재기동 정책은 그 트윈의 선언이므로 그대로 지킨다. */
+      const res = await TwinEngine.ingestMaster(
+        domainId,
+        master,
+        readRestartPolicy(inst.restartPolicy, `resync of twin "${instanceId}"`),
+        keepSpace ? { spaceId: keepSpace } : undefined,
+        context.state.user
+      )
       return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings: res.warnings }
     } catch (e: any) {
       return refusal(context, e, 'resync failed')
@@ -273,10 +291,14 @@ export class TwinReferenceResolver {
 
   /** 템플릿 + 노브 → 합성 마스터 → 인제스트(+기동+시나리오). 레퍼런스 import 와 같은 경로, 원천만 합성. */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, { description: 'Instantiate a twin template with params → synthetic master → ingest (+start+scenario). Returns {ok, instanceId, spaceId}.' })
+  @Mutation(returns => ScalarObject, {
+    description:
+      "Instantiate a twin template with params → synthetic master → ingest (+start+scenario). restartPolicy declares how the new twin treats its own past on reboot ('resync' | 'resume' | 'reset') — there is no default. Returns {ok, instanceId, spaceId}."
+  })
   async createFromTemplate(
     @Arg('templateId') templateId: string,
     @Arg('params', type => ScalarObject) params: any,
+    @Arg('restartPolicy') restartPolicy: string,
     @Ctx() context: ResolverContext,
     @Arg('start', { nullable: true }) start?: boolean,
     @Arg('spaceId', { nullable: true, description: 'Existing space to co-locate this twin into (add a lens to a site). Omit to create its own space.' }) spaceId?: string
@@ -310,7 +332,13 @@ export class TwinReferenceResolver {
       master.origin = { kind: 'template', templateId, params: effective, ...(spaceId ? { spaceId } : {}) }
       /* 공간 선택은 템플릿을 거치지 않는다 — 템플릿마다 이 노브를 알고 있어야 한다면 새 템플릿이
          조용히 무시하게 된다. 합성된 마스터에 한 곳에서 얹는다(레퍼런스 인제스트와 같은 경로). */
-      const res = await TwinEngine.ingestMaster(domainId, master, { spaceId }, context.state.user)
+      const res = await TwinEngine.ingestMaster(
+        domainId,
+        master,
+        readRestartPolicy(restartPolicy, `createFromTemplate("${templateId}")`),
+        { spaceId },
+        context.state.user
+      )
       if (start !== false) {
         await TwinEngine.startFromRegistry(domainId, res.instanceId)
         if (scenario) {
@@ -545,14 +573,18 @@ export class TwinReferenceResolver {
    * 넣는 것도 거절(`refuseImportSpace`) — 서로 다른 현장이 조용히 합쳐지는 것을 막는다.
    */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, { description: 'Create twins from a reference: discover sites → filter by siteIds (if given) → fetch master(s) → provision. spaceId co-locates the twin into an existing space (one site only). start=false to only provision; live=true to run as a mirror (adapter openLiveFeed → live projector) instead of sim.' })
+  @Mutation(returns => ScalarObject, {
+    description:
+      "Create twins from a reference: discover sites → filter by siteIds (if given) → fetch master(s) → provision. spaceId co-locates the twin into an existing space (one site only). start=false to only provision; live=true to run as a mirror (adapter openLiveFeed → live projector) instead of sim. restartPolicy declares how each new twin treats its own past on reboot ('resync' | 'resume' | 'reset'); omit it and live=true implies 'resync' — a mirror reads the source again — while a simulation must declare 'resume' or 'reset' for itself."
+  })
   async importTwinReference(
     @Arg('source') source: string,
     @Ctx() context: ResolverContext,
     @Arg('siteIds', type => [String], { nullable: true }) siteIds?: string[],
     @Arg('start', { nullable: true }) start?: boolean,
     @Arg('live', { nullable: true }) live?: boolean,
-    @Arg('spaceId', { nullable: true, description: 'Existing space to co-locate this twin into (add a lens to a site). Only when importing a single site. Omit to give each site its own space.' }) spaceId?: string
+    @Arg('spaceId', { nullable: true, description: 'Existing space to co-locate this twin into (add a lens to a site). Only when importing a single site. Omit to give each site its own space.' }) spaceId?: string,
+    @Arg('restartPolicy', { nullable: true, description: "How each new twin treats its own past on reboot: 'resync' | 'resume' | 'reset'. Required unless live=true (a mirror is 'resync' by definition)." }) restartPolicy?: string
   ): Promise<any> {
     const domainId = context.state.domain.id
     const repo = getRepository(TwinReference)
@@ -574,9 +606,16 @@ export class TwinReferenceResolver {
           const master = await adapter.fetchMaster(cfg, site)
           /* 어느 레퍼런스의 **어느 사이트**에서 왔는지 남긴다 — 다시 읽기가 같은 어댑터·같은 사이트로 돌아오려면
              사이트 정체가 있어야 한다(`source` 는 참조 이름이라 사이트 전부에 같다). */
+          /*
+           * 정책은 **선언이거나 의도에서 곧바로 따라오는 것**이다: `live=true` 는 미러를 띄우겠다는 뜻이고
+           * 미러는 정의상 `resync` 다(외부가 진실이므로 우리 과거를 이어 붙이지 않는다). 시뮬로 띄우려면
+           * 스스로 선언해야 한다 — 그 자리에서 우리가 고르면 재기동마다 이력을 지우는 트윈이 조용히 생긴다.
+           */
+          const policy = readRestartPolicy(restartPolicy ?? (live ? 'resync' : undefined), `importTwinReference("${source}")`)
           const res = await TwinEngine.ingestMaster(
             domainId,
             { ...master, origin: { kind: 'reference', source, siteId: site.siteId, ...(spaceId ? { spaceId } : {}) } },
+            policy,
             { spaceId },
             context.state.user
           )

package/server/service/twin-audit/command-audit.ts

@@ -17,6 +17,19 @@ export type CommandAuditInput = {
   command: any
   /** 커널 판정. */
   ack: { accepted?: boolean; errorCode?: string; error?: string }
+  /**
+   * **원본(어댑터)이 준 답** — 허락과 일어남 사이에 끼어 있는 것을 같은 기록에 닫는다 (ADR-0029 §1 결정 C).
+   *
+   * ── 왜 이 칸이 필요한가 ──────────────────────────────────────────────────
+   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 조용히 실패하면 원장에는 승인만
+   * 남는다. 그래서 어댑터의 답을 **같은 행**에 되적는다.
+   *
+   * 셋을 구별한다:
+   *  · 없음(`undefined`) — **원본에 묻지 않았다**(커널이 받은 명령이다). 「모른다」와 다르다.
+   *  · `{ answered: false }` — 물었는데 **답을 못 받았다** → `unknown` 으로 남긴다. 성공으로 적지 않는다.
+   *  · `{ answered: true, ok, code? }` — 원본이 답했다(적용·거절 모두 사실이다).
+   */
+  source?: { answered: boolean; ok?: boolean; code?: string }
   /** 세션이 아는 사용자 — **서버만 채운다.** */
   actor?: { id?: string; email?: string; name?: string }
   /** 서버 시각. 호출부가 주입해 테스트가 시간을 고정할 수 있게 한다. */
@@ -35,6 +48,13 @@ export type CommandAuditRow = {
   actorName?: string
   accepted: boolean
   errorCode?: string
+  /**
+   * 원본이 그래서 어떻게 했나 — `applied` · `refused` · `unknown`(물었지만 답이 없다).
+   * **없으면 묻지 않은 것이다**(커널이 받은 명령). 0 이나 성공으로 채우지 않는다.
+   */
+  sourceOutcome?: 'applied' | 'refused' | 'unknown'
+  /** 원본이 준 사유 코드 — 있으면 그대로. 우리가 지어내지 않는다. */
+  sourceCode?: string
   args?: any
   argsTruncated: boolean
 }
@@ -48,7 +68,7 @@ export function normalizeOrigin(v: unknown): CommandOrigin {
 const ARGS_MAX = 4000
 
 export function buildCommandAudit(input: CommandAuditInput): CommandAuditRow {
-  const { command, ack, actor, at } = input
+  const { command, ack, actor, at, source } = input
   const argsText = safeJson(command?.args)
   const truncated = argsText !== null && argsText.length > ARGS_MAX
   return {
@@ -57,6 +77,8 @@ export function buildCommandAudit(input: CommandAuditInput): CommandAuditRow {
     commandType: str(command?.type),
     origin: normalizeOrigin(command?.origin),
     reason: str(command?.reason),
+    /* 원본의 답 — 묻지 않았으면 칸을 만들지 않는다(모름과 구별한다). */
+    ...(source ? { sourceOutcome: sourceOutcomeOf(source), ...(source.code ? { sourceCode: source.code } : {}) } : {}),
     /* 신원 — 세션 값만. 커맨드에 실려 온 신원 주장은 쳐다보지 않는다. */
     actorId: str(actor?.id),
     actorEmail: str(actor?.email),
@@ -79,3 +101,14 @@ function safeJson(v: unknown): string | null {
     return null /* 순환 참조 등 — 못 재면 자르지 않는다(원본을 그대로 둔다) */
   }
 }
+
+/**
+ * 원본의 답을 세 값으로 — **답이 없으면 `unknown`**(성공으로 적지 않는다).
+ *
+ * 이 함수가 있는 이유: 「물었지만 답이 없다」를 실패로도 성공으로도 적을 수 없다. 실패로 적으면 일어난 일을
+ * 없던 일로 만들고, 성공으로 적으면 없던 일을 일어난 일로 만든다. 셋째 값이 사실이다.
+ */
+export function sourceOutcomeOf(source: { answered: boolean; ok?: boolean }): 'applied' | 'refused' | 'unknown' {
+  if (!source.answered || typeof source.ok !== 'boolean') return 'unknown'
+  return source.ok ? 'applied' : 'refused'
+}

package/server/service/twin-audit/twin-audit-event.ts

@@ -99,6 +99,26 @@ export class TwinAuditEvent {
   reason?: string
 
   /* ── 신원: 세션에서만 온다 ── */
+  /*
+   * **원본이 그래서 어떻게 했나** — 허락과 일어남 사이에 끼어 있는 것을 같은 행에 닫는다
+   * (ADR-0029 §1 결정 C, 2026-08-19).
+   *
+   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 조용히 실패하면 원장에는 승인만
+   * 남는다. 그래서 어댑터의 답을 되적는다.
+   *
+   *  · 비어 있음 — **원본에 묻지 않았다**(커널이 받은 명령이다). 「모른다」와 다르다.
+   *  · `unknown` — 물었는데 **답을 못 받았다**. 성공으로 적지 않는다.
+   *  · `applied` · `refused` — 원본이 답했다(둘 다 사실이다).
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: "What the source did with it: 'applied' | 'refused' | 'unknown' (asked but no answer). Empty means the source was not asked — the kernel took the command." })
+  sourceOutcome?: string
+
+  /** 원본이 준 사유 코드 — 있으면 그대로 적는다(우리가 지어내지 않는다). */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Reason code the source returned, as it gave it.' })
+  sourceCode?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'Approving user id, stamped by the server from the session.' })
   actorId?: string

package/server/service/twin-control/twin-control-mutation.ts

@@ -1,4 +1,4 @@
-import { Arg, Ctx, Mutation, Resolver, Directive} from 'type-graphql'
+import { Arg, Ctx, Mutation, Query, Resolver, Directive } from 'type-graphql'
 
 import { validateScenario } from '@operato/twin-kernel'
 
@@ -9,6 +9,8 @@ import { getRepository } from '@things-factory/shell'
 import { TwinEngine } from '../../engine/index.js'
 import { TwinAuditEvent } from '../twin-audit/twin-audit-event.js'
 import { buildCommandAudit } from '../twin-audit/command-audit.js'
+/* 구동은 원본을 지난다(ADR-0029 §8) — 트윈 런타임을 직접 잡지 않는다. */
+import { routeControl, controlCapabilityOf } from '../reference/control-routing.js'
 
 /*
  * 트윈 Command·Scenario 채널 — 상향 mutation.
@@ -61,42 +63,87 @@ export class TwinControlMutation {
     return { accepted: !!ack?.accepted, error: ack?.error, errorCode: ack?.errorCode, errorParams: ack?.errorParams }
   }
 
-  /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */
+  /**
+   * 구동 채널 — **원본을 지난다**(ADR-0029 §8).
+   *
+   * ── 무엇이 바뀌었나 (2026-08-19) ──────────────────────────────────────────
+   * 예전에는 이 문이 `TwinEngine.runtime(...).scenario` 를 **직접** 잡았다. 시뮬만 할 수 있는 일(자극·배속·
+   * 정지)이 계약 밖의 지름길로 들어온 셈이고, 실 시스템에는 그 자리가 아예 없었다. 이제 길은 하나다:
+   * 트윈 → 그 트윈의 원본 → 어댑터가 **선언한** `control` 능력. 선언하지 않은 원본에는 문이 열리지 않고,
+   * 그 사실을 사유 코드로 말한다(`not-declared`) — 실 WMS 가 정지되지 않는 것은 결손이 아니다.
+   *
+   * 반환을 Boolean 에서 객체로 바꿨다: 예전에는 거절 사유를 실을 자리가 없어 **로그로만** 남겼다.
+   * 화면은 왜 안 되는지 알 수 없었다.
+   */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => Boolean, { description: 'control twin scenario (load|start|pause|setSpeed)' })
-  async controlTwinScenario(
+  @Mutation(returns => ScalarObject, {
+    description:
+      "Drive the source behind a twin: stimulus | start | pause | speed | reset. The command goes through the source adapter's declared control capability — a source that does not declare it refuses with code 'not-declared' (a real system is not paused or seeded, and that is a fact rather than a gap). Returns { ok, code?, detail? }."
+  })
+  async controlTwinSource(
     @Arg('instanceId') instanceId: string,
     @Arg('action') action: string,
     @Ctx() context: ResolverContext,
-    @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any
-  ): Promise<boolean> {
+    @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any,
+    @Arg('speed', { nullable: true }) speed?: number
+  ): Promise<any> {
     const domainId = context.state.domain?.id
-    /* 테넌트 격리 — 레지스트리를 직접 색인하지 않는다(키에 도메인이 들어 있다). */
-    if (!TwinEngine.owns(domainId, instanceId)) return false
-    const runtime = TwinEngine.runtime(domainId, instanceId)
+    if (!domainId) return { ok: false, code: 'no-domain' }
+    const allowed = ['stimulus', 'start', 'pause', 'speed', 'reset']
+    if (!allowed.includes(action)) return { ok: false, code: 'unsupported-action', detail: `one of ${allowed.join(' | ')}` }
     /*
-     * 자극 주입 가드 — mirror 트윈(외부 실물이 진실)은 커널 시나리오 엔진이 없다(startLive=projector, runtime 없음).
-     * what-if 를 여기에 주입하면 현실을 오염시키므로 거부한다(sim-experiment/sim-world 만 자극 가능). silent throw 방지.
+     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour` 를
+     * 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다). 규칙은 커널이
+     * 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.
      */
-    if (!runtime?.scenario) return false
+    if (action === 'stimulus') {
+      const v = validateScenario(scenario)
+      if (v.ok === false) return { ok: false, code: 'invalid', detail: v.errorCode, params: v.errorParams }
+    }
+    if (action === 'speed' && !(Number(speed) > 0)) return { ok: false, code: 'invalid', detail: 'speed must be greater than 0' }
+
     /*
-     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour`
-     * 를 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다).
-     * 규칙은 커널이 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.
+     * **구동도 사람이 한 일이다 — 남긴다** (ADR-0029 §1 결정 C, 2026-08-19).
+     *
+     * 이 문은 감사를 아예 남기지 않았다. 그런데 자극을 바꾸고 배속을 올리고 원본을 멈추는 것은 그 트윈의
+     * 사실을 바꾸는 행위다 — 커맨드 채널은 남기는데 이쪽이 비어 있으면, 나중에 「무엇이 이 공장을
+     * 흔들었나」에 답할 수 없다.
+     *
+     * 결정 C 그대로: 게이트는 여기 남고(위 `@privilege`), **원본의 답을 같은 행에 닫는다.** 답을 못 받으면
+     * `unknown` 이다 — 성공으로 적지 않는다.
      */
-    if (action === 'load') {
-      const v = validateScenario(scenario)
-      if (v.ok === false) {
-        /* 사유를 로그로 남긴다 — 이 뮤테이션의 반환은 Boolean 계약이라 사유를 실어 보낼 자리가 없다. */
-        console.warn(`[twin] scenario rejected for "${instanceId}": ${v.errorCode} ${JSON.stringify(v.errorParams ?? {})}`)
-        return false
-      }
+    let result: { ok: boolean; code?: string; detail?: string }
+    try {
+      result = await routeControl(domainId, instanceId, { action: action as any, scenario, speed: speed != null ? Number(speed) : undefined })
+    } catch (e: any) {
+      result = { ok: false, code: 'failed', detail: e?.message ?? 'control failed' }
     }
-    if (action === 'load' && scenario) runtime.scenario.load(scenario)
-    else if (action === 'start') runtime.scenario.start()
-    else if (action === 'pause') runtime.scenario.pause()
-    else if (action === 'setSpeed' && scenario?.speed != null) runtime.scenario.setSpeed(Number(scenario.speed))
-    else return false
-    return true
+    try {
+      const audit = buildCommandAudit({
+        /* 커맨드 채널과 같은 모양으로 적는다 — 감사를 읽는 쪽이 두 어휘를 배우지 않게. */
+        command: { type: `source.${action}`, origin: 'user', args: { ...(scenario ? { scenario } : {}), ...(speed != null ? { speed } : {}) } },
+        /* 게이트는 통과했다(여기까지 왔다) — 그 사실과 원본의 답은 다른 칸이다. */
+        ack: { accepted: true },
+        source: { answered: typeof result?.ok === 'boolean', ok: result?.ok, code: result?.code },
+        actor: context.state.user,
+        at: new Date()
+      })
+      const repo = getRepository(TwinAuditEvent)
+      await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))
+    } catch (err) {
+      /* 기록이 실패해도 결과는 돌려준다 — 다만 삼키지 않는다(「기록 없음」과 「일 없음」을 구별해야 한다). */
+      console.error(`[twin-control] source control audit not recorded for "${instanceId}"`, err)
+    }
+    return result
+  }
+
+  /** 이 트윈의 원본이 **무엇을 받을 수 있나** — 화면이 버튼을 열기 전에 묻는 자리. */
+  @Query(returns => ScalarObject, {
+    description: "What the source behind this twin can do: its declared capabilities ('live', 'control'). Empty when the twin has no source or its adapter declares nothing."
+  })
+  async twinSourceCapability(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any> {
+    const domainId = context.state.domain?.id
+    if (!domainId) return { capabilities: [] }
+    return controlCapabilityOf(domainId, instanceId)
   }
 }

package/server/service/twin-instance/twin-instance.ts

@@ -61,19 +61,25 @@ export class TwinInstance {
   kind: string
 
   /*
-   * realityMode — 이 트윈의 현실이 어디서 오는가(runtime-state-model §0·§1 "지속 현실 하나 + 여러 렌즈"의 ① 선언).
-   * 'mirror'         = 현실은 외부 실물 시스템. 트윈=순수 렌즈, 재기동 시 실물서 재동기(startLive).
-   * 'sim-world'      = 트윈이 낳은 타임라인이 곧 진실이며 이어진다 → 재기동 시 저널서 resume(현실 지속).
-   * 'sim-experiment' = seed 재현형. 재기동 = 같은 우주 재실행(저널 reset, revision 0) — 백지 시작이 버그가 아니라 선언된 거동.
+   * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나(ADR-0029 §2).
    *
-   * **비어 있을 수 없다.** 이 값은 재기동 거동을 구분하는 선언이고, 없으면 읽는 쪽마다 각자
-   * 기본값을 고르게 된다 — 같은 트윈이 부르는 자리에 따라 다르게 재기동하는 길이다.
-   * 선언을 생략한 프로비저닝은 `register` 가 `DEFAULT_REALITY_MODE` 로 **각인해서 저장한다**.
-   * 즉 "미선언" 이라는 상태 자체를 저장소에 두지 않는다.
+   *   'resync' = 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다 → startLive).
+   *   'resume' = 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).
+   *   'reset'  = 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험 — 백지 시작이 선언된 거동이다).
+   *
+   * ── 왜 트윈에 남았나 (옛 이름 `realityMode`) ────────────────────────────────
+   * 「현실이 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) —
+   * 트윈은 한 종류이고 언제나 원본을 반영한다. 그런데 코드가 이 축으로 실제로 가른 것은 **재기동 거동
+   * 하나**였고, 그것은 원본의 성질이 아니라 **트윈과 자기 과거의 관계**다: 같은 시뮬레이터 원본을 보는 두
+   * 트윈이 하나는 이어가고 하나는 매번 처음부터 재현할 수 있다. 그래서 축은 남고 이름만 바뀌었다.
+   *
+   * **비어 있을 수 없고, 기본값도 없다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로
+   * 떨어졌다 — 값이 하나 어긋나는 순간 이력을 지우는 길이다. 이제 읽는 쪽이 **던진다**
+   * (`engine/restart-policy.ts`). 선언은 프로비저닝하는 쪽의 몫이다.
    */
   @Column()
-  @Field({ description: "Reality source declaration: 'mirror' (external system is truth, resync on reboot) | 'sim-world' (generated timeline is truth and persists, resume on reboot) | 'sim-experiment' (seed-reproducible, resets on reboot)." })
-  realityMode: string
+  @Field({ description: "Restart policy: 'resync' (read again from the external source) | 'resume' (continue this twin's own journal) | 'reset' (wipe and replay from the seed). No default — an unspecified policy is refused." })
+  restartPolicy: string
 
   /* 읽을 때 어휘 세대를 흡수한다(`nodes`/`movers`/`equipmentList` → `locations`/`equipment`).  (vocabulary-guard: allow — 세대 이름 없이는 설명할 수 없다.)
      자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠지고, 빠진 것은 오류가 아니라 **빈 공장**이라

package/server/service/twin-lifecycle/twin-lifecycle-mutation.ts

@@ -14,7 +14,8 @@ import { domainCatalog } from './domain-catalog.js'
  * 트윈 인스턴스 생명주기 채널 — 프로비저닝(상향, ADR-0015).
  * State/Command/Scenario 는 이미 running 인 인스턴스를 다루지만, 이 채널은 인스턴스 자체를 만들고/설정하고/없앤다.
  * 생명주기: provision(save, 미기동) → start → stop → delete. 모두 domain 스코프(context.state.domain.id).
- * model(TwinModelDef+layout)=구조, scenario=자극 은 분리 — 여기선 구조만 세운다. 자극은 controlTwinScenario 로.
+ * model(TwinModelDef+layout)=구조, scenario=자극 은 분리 — 여기선 구조만 세운다. 자극은 **원본이 선언하고**
+ * (`TwinReference.connectionConfig.scenario`) 기동이 싣거나, 원본의 구동 능력으로 태운다(ADR-0029 §4·§8).
  */
 @Resolver()
 export class TwinLifecycleMutation {

package/server/service/twin-model/twin-model-query.ts

@@ -374,7 +374,7 @@ export class TwinModelQuery {
       })(),
       description: inst.description ?? null,
       kind: inst.kind,
-      realityMode: inst.realityMode,
+      restartPolicy: inst.restartPolicy,
       source: ref
         ? { referenceId: ref.source, adapterType: ref.adapterType, status: ref.status, lastSyncedAt: ref.lastSyncedAt }
         : null,

package/test/adopt-structure-live.test.ts

@@ -63,8 +63,8 @@ before(async () => {
   const d = await ds.getRepository(Domain).save({ name: 'adopt-test', subdomain: 'adopt-test' } as any)
   domainId = d.id
 
-  await TwinEngine.ingestMaster(domainId, master(MIRROR, 3, 2))
-  await TwinEngine.ingestMaster(domainId, master(SIM, 3, 2))
+  await TwinEngine.ingestMaster(domainId, master(MIRROR, 3, 2), 'reset')
+  await TwinEngine.ingestMaster(domainId, master(SIM, 3, 2), 'reset')
 })
 
 after(async () => {
@@ -74,10 +74,10 @@ after(async () => {
 
 test('돌고 있는 미러는 멈추지 않고 갈아탄다 — 세 층이 함께 움직인다', async () => {
   /* 미러 기동은 선언 기반 부팅이 가른다 — `startFromRegistry` 는 시뮬 경로다(같은 함수가 아니다). */
-  const rt = await TwinEngine.bootDeclared(domainId, MIRROR, 'mirror')
+  const rt = await TwinEngine.bootDeclared(domainId, MIRROR, 'resync')
   assert.equal(rt.mode, 'live', '미러로 떠야 이 검사가 뜻이 있다')
 
-  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 2))
+  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 2), 'reset')
 
   /* ① 리비전 — 이후 이벤트가 달고 다닐 번호가 올라간다 */
   const revs = await ds.getRepository(TwinStructure).find({ where: { instanceId: MIRROR }, order: { rev: 'ASC' } })
@@ -101,7 +101,7 @@ test('돌고 있는 미러는 멈추지 않고 갈아탄다 — 세 층이 함
 })
 
 test('사라진 설비를 수로 알린다 — 자리가 수천인 현장에서 직접 세어 보게 하지 않는다', async () => {
-  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 1)) // 지게차 2 → 1
+  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 1), 'reset') // 지게차 2 → 1
   const adopted = res.warnings.find((w: any) => w.code === 'structure-adopted')
   assert.equal(adopted.params.equipmentDropped, 1)
 
@@ -111,10 +111,10 @@ test('사라진 설비를 수로 알린다 — 자리가 수천인 현장에서
 })
 
 test('돌고 있는 시뮬레이션은 여전히 거절한다 — 조건이 바뀐 실험은 다른 실험이다', async () => {
-  await TwinEngine.bootDeclared(domainId, SIM, 'sim-experiment')
+  await TwinEngine.bootDeclared(domainId, SIM, 'reset')
   const before = (await ds.getRepository(TwinStructure).find({ where: { instanceId: SIM } })).length
 
-  await assert.rejects(() => TwinEngine.ingestMaster(domainId, master(SIM, 9, 2)), /is running/)
+  await assert.rejects(() => TwinEngine.ingestMaster(domainId, master(SIM, 9, 2), 'reset'), /is running/)
 
   assert.equal(
     (await ds.getRepository(TwinStructure).find({ where: { instanceId: SIM } })).length,

package/test/boot-resume.test.ts

@@ -43,14 +43,14 @@ test('부팅이 런타임까지 되살린다 — 상태 복구만으로는 도
 
 test('모드를 지어내지 않는다 — 미러였던 것은 미러로 되살린다', () => {
   const body = methodOf(engine, 'resumeRow')
-  assert.match(body, /realityMode === 'mirror'/, '선언된 모드를 보고 갈라야 한다')
+  assert.match(body, /restartPolicy === 'resync'/, '선언된 모드를 보고 갈라야 한다')
   assert.match(body, /this\.startLive\(/, '미러는 관측 구동으로 세운다')
   assert.match(body, /this\.startFromRegistry\(/, '시뮬은 등록부의 모드 그대로 세운다')
   /*
    * 미러 가지 안을 그대로 떠서 본다 — 미러를 시뮬로 세우면 관측 트윈이 **스스로 물건을 옮긴다**
    * (없던 움직임을 만드는 것이다). 단어의 거리로 재면 로그·주석에 걸려 헛돈다.
    */
-  const at = body.indexOf("realityMode === 'mirror'")
+  const at = body.indexOf("restartPolicy === 'resync'")
   const mirrorBranch = body.slice(at, body.indexOf('} else {', at))
   assert.match(mirrorBranch, /startLive\(/, '미러 가지는 관측 구동으로 세워야 한다')
   assert.equal(mirrorBranch.includes('startFromRegistry'), false, '미러 가지에서 시뮬 기동을 부른다 — 없던 움직임을 만든다')
@@ -72,7 +72,7 @@ test('벤치 사본은 무인으로 되살아나지 않는다 — 실험은 재
 
 test('피드 재개는 등록부가 「도는 미러」라고 말하는 것만 — 멈춘 것을 다시 켜지 않는다', () => {
   assert.match(live, /export async function resumeReferenceLiveFeeds/, '재개 함수가 있어야 한다')
-  assert.match(live, /r\.status === 'running' && r\.realityMode === 'mirror'/, '도는 미러만 골라야 한다')
+  assert.match(live, /r\.status === 'running' && r\.restartPolicy === 'resync'/, '도는 미러만 골라야 한다')
   assert.match(live, /discoverSites/, '사이트 서술자는 다시 찾아서 얻는다(hint 를 남기지 않았다)')
   /* 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다 — 조용히 넘기지 않는다. */
   assert.match(live, /NOT reattached/, '못 붙인 것은 이유와 함께 남겨야 한다')