@things-factory/headless-twin 10.0.0-zeta.10

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@things-factory/headless-twin",
+  "version": "10.0.0-zeta.10",
+  "main": "dist-server/index.js",
+  "things-factory": true,
+  "author": "heartyoh <heartyoh@hatiolab.com>",
+  "description": "Headless digital-twin host — operato-twin kernel(WMS/YMS/MES) 를 things-factory 모듈로 호스팅(State GraphQL subscription + 이벤트 영속 + 워커 tick + command/scenario mutation).",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "@things-factory:registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hatiolab/things-factory.git",
+    "directory": "packages/headless-twin"
+  },
+  "scripts": {
+    "build": "npm run clean:server && tsc",
+    "build:server": "npm run clean:server && tsc",
+    "clean:server": "rm -rf dist-server",
+    "clean": "npm run clean:server",
+    "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@operato/twin-kernel": "^0.0.2",
+    "@things-factory/auth-base": "^10.0.0-zeta.10",
+    "@things-factory/env": "^10.0.0-zeta.10",
+    "@things-factory/shell": "^10.0.0-zeta.10"
+  },
+  "gitHead": "66f0cf11f6a6ddc4ad756a55fa13b26a55d89fd4"
+}

package/server/engine/index.ts

@@ -0,0 +1 @@
+export * from './twin-engine.js'

package/server/engine/twin-engine.ts

@@ -0,0 +1,160 @@
+/*
+ * TwinEngine — operato-twin 커널 인스턴스를 things-factory 위에서 호스팅.
+ * integration-base 의 ScenarioEngine 패턴 미러: 메모리 인스턴스 맵 + 백그라운드 tick + pubsub 상태 발행.
+ *
+ * 커널(zero-dep, ESM+CJS 이중배포)은 CJS require 로 로드(Node 20 CommonJS 소비 — require(ESM) 회피).
+ * 커널은 결정적 논리 연산 코어 — 이 host 가 전송(pubsub)·영속(TypeORM)·스케줄(tick)·복구(replay)만 얇게 래핑.
+ * (설계 SoT: operato-twin/design/integration/things-factory-host.md)
+ */
+
+import { pubsub, getRepository } from '@things-factory/shell'
+
+import { TwinEvent } from '../service/twin-event/twin-event.js'
+import { TwinInstance } from '../service/twin-instance/twin-instance.js'
+
+import type { TwinKernel, BoardDef, SubscriptionMessage, TwinRuntime as TwinRuntimeType } from '@operato/twin-kernel'
+
+/* 커널 런타임 로드 — CJS 번들(dist-cjs). 타입은 위 import type 로. replay = 이벤트열→상태 재구성(복구·시간여행). */
+const { WmsKernel, YmsKernel, MesKernel, TwinRuntime, replay } = require('@operato/twin-kernel')
+
+const KERNELS: Record<string, any> = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel }
+
+/* 인메모리 라이브 런타임 홀더(영속 엔티티 TwinInstance 와 구분). */
+interface InstanceRuntime {
+  id: string
+  domainId: string
+  runtime: TwinRuntimeType
+  unsub: () => void
+  timer?: any
+}
+
+export class TwinEngine {
+  static instances: Record<string, InstanceRuntime> = {}
+  /** 라이브 런타임이 없을 때(복구 후 미기동) 저널에서 재구성한 상태 캐시. */
+  static recovered: Record<string, any> = {}
+  static TICK_MS = 1000
+
+  /**
+   * 부팅 훅 — DB 에 status='running' 으로 남은 인스턴스를 저널에서 상태 재구성(DB→replay).
+   * 라이브 tick 재개(sim 결정적 re-run / live 인제스트 지속)는 후속. 여기선 상태 복원 + 노출.
+   */
+  static async bootstrap(): Promise<void> {
+    try {
+      const rows = await getRepository(TwinInstance).find({ where: { status: 'running' } })
+      for (const row of rows) {
+        if (!row.domainId || !row.instanceId) continue
+        const state = await this.recover(row.domainId, row.instanceId).catch(() => null)
+        if (state) {
+          this.recovered[row.instanceId] = { revision: state.revision, state }
+          console.log(`[twin-engine] recovered "${row.instanceId}" from journal → revision ${state.revision}.`)
+        }
+      }
+    } catch (err) {
+      console.error('[twin-engine] recovery scan failed', err)
+    }
+  }
+
+  /** 트윈 인스턴스 시작 — 커널 생성 + 보드 로드 + State 스트림 브리지 + 워커 tick + 레지스트리 영속. */
+  static start(id: string, domainId: string, kind: string, board: BoardDef): InstanceRuntime {
+    if (this.instances[id]) return this.instances[id]
+
+    const Kernel = KERNELS[kind] ?? WmsKernel
+    const kernel: TwinKernel = new Kernel(domainId)
+    kernel.loadBoard(board)
+    const runtime: TwinRuntimeType = new TwinRuntime(kernel)
+
+    /* State 채널: runtime.subscribe(snapshot→delta→clock) → pubsub 방송(구독 리졸버가 instanceId 필터). */
+    const sub = runtime.subscribe((msg: SubscriptionMessage) => {
+      pubsub.publish('twin-state', {
+        twinState: { instanceId: id, kind: msg.kind, revision: (msg as any).revision, payload: msg }
+      })
+      /* 영속: 이벤트(delta)만 append-only 저장. 재부팅 시 이 저널을 replay 해 복구. */
+      if (msg.kind === 'delta') this.persist(domainId, id, msg).catch(err => console.error('twin persist fail', err))
+    })
+
+    /* subscribe 는 RuntimeSubscription({ unsubscribe() }) 반환 → () => void 로 감쌈. */
+    const inst: InstanceRuntime = { id, domainId, runtime, unsub: () => sub.unsubscribe() }
+    this.instances[id] = inst
+    delete this.recovered[id] // 라이브가 우선
+
+    /* 복구 앵커: 레지스트리에 board/kind/status 영속(재부팅 시 이게 있어야 replay 가능). */
+    this.register(domainId, id, kind, board).catch(err => console.error('twin register fail', err))
+
+    /* 워커 tick — 스켈레톤은 setInterval(메인 루프). 긴 시뮬 오프-루프(worker thread)는 스케일 하드닝(향후, §host 경계). */
+    inst.timer = setInterval(() => runtime.tick(this.TICK_MS), this.TICK_MS)
+    return inst
+  }
+
+  /** 레지스트리 upsert(도메인+instanceId 유니크). */
+  static async register(domainId: string, instanceId: string, kind: string, board: BoardDef): Promise<void> {
+    const repo = getRepository(TwinInstance)
+    const existing = await repo.findOne({ where: { domain: { id: domainId }, instanceId } })
+    await repo.save(
+      repo.create({
+        ...(existing ?? {}),
+        domain: { id: domainId } as any,
+        instanceId,
+        kind,
+        board,
+        status: 'running'
+      })
+    )
+  }
+
+  static async persist(domainId: string, instanceId: string, msg: any): Promise<void> {
+    const repo = getRepository(TwinEvent)
+    const e = msg.event
+    await repo.save(
+      repo.create({
+        domain: { id: domainId } as any,
+        instanceId,
+        tenantId: e?.tenantId,
+        eventType: e?.eventType,
+        revision: msg.revision,
+        eventTime: e?.eventTime,
+        payload: e
+      })
+    )
+  }
+
+  /**
+   * 재부팅 복구 / 시간여행 — DB 저널을 replay 해 상태 재구성.
+   * board 는 레지스트리(TwinInstance)에서, 이벤트는 TwinEvent(revision ASC)에서. untilRevision 지정 시 그 시점까지.
+   */
+  static async recover(domainId: string, instanceId: string, untilRevision?: number): Promise<any> {
+    const reg = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
+    if (!reg?.board) throw new Error(`twin instance "${instanceId}" not registered (no board to replay)`)
+
+    const rows = await getRepository(TwinEvent).find({
+      where: { domain: { id: domainId }, instanceId },
+      order: { revision: 'ASC' }
+    })
+    const events = rows
+      .filter(r => untilRevision == null || (r.revision ?? 0) <= untilRevision)
+      .map(r => r.payload)
+      .filter(Boolean)
+
+    return replay(reg.board as BoardDef, events)
+  }
+
+  static async stop(id: string): Promise<void> {
+    const i = this.instances[id]
+    if (i) {
+      clearInterval(i.timer)
+      i.unsub()
+      delete this.instances[id]
+      await getRepository(TwinInstance)
+        .update({ domain: { id: i.domainId }, instanceId: id }, { status: 'stopped' })
+        .catch(err => console.error('twin deregister fail', err))
+    }
+  }
+
+  static runtime(id: string): TwinRuntimeType | undefined {
+    return this.instances[id]?.runtime
+  }
+
+  /** 현재 전체 스냅샷 — 라이브 우선, 없으면 저널 복구 캐시. */
+  static snapshot(id: string): any {
+    return this.instances[id]?.runtime.resync() ?? this.recovered[id]
+  }
+}

package/server/index.ts

@@ -0,0 +1,16 @@
+export * from './engine/index.js'
+export * from './service/index.js'
+
+import './routes.js'
+
+import { TwinEngine } from './engine/index.js'
+
+/* 모듈 부팅 — 영속 인스턴스 복구 훅(향후). 지금은 명시 start(mutation/부팅 설정)로 인스턴스 생성. */
+process.on('bootstrap-module-start' as any, async ({ app, config, client }: any) => {
+  try {
+    await TwinEngine.bootstrap()
+    console.log('Headless Twin host has started.')
+  } catch (ex) {
+    console.error('Headless Twin host failed to start.', ex)
+  }
+})

package/server/routes.ts

@@ -0,0 +1,5 @@
+/* 헤드리스 트윈은 GraphQL(subscription/mutation)로 동작 — REST 라우터는 미사용(빈 부트스트랩). */
+process.on('bootstrap-module-global-public-route' as any, (app, globalPublicRouter) => {})
+process.on('bootstrap-module-global-private-route' as any, (app, globalPrivateRouter) => {})
+process.on('bootstrap-module-domain-public-route' as any, (app, domainPublicRouter) => {})
+process.on('bootstrap-module-domain-private-route' as any, (app, domainPrivateRouter) => {})

package/server/service/index.ts

@@ -0,0 +1,32 @@
+/* EXPORT ENTITY TYPES */
+export * from './twin-event/twin-event.js'
+export * from './twin-instance/twin-instance.js'
+export * from './twin-state/twin-state-subscription.js'
+
+/* IMPORT ENTITIES AND RESOLVERS */
+import { entities as TwinEventEntities } from './twin-event/index.js'
+import { entities as TwinInstanceEntities } from './twin-instance/index.js'
+import { resolvers as TwinStateResolvers } from './twin-state/index.js'
+import { resolvers as TwinControlResolvers } from './twin-control/index.js'
+import { resolvers as TwinLifecycleResolvers } from './twin-lifecycle/index.js'
+import { resolvers as TwinJournalResolvers } from './twin-journal/index.js'
+
+export const entities = [
+  /* ENTITIES */
+  ...TwinEventEntities,
+  ...TwinInstanceEntities
+]
+
+export const subscribers = []
+
+export const schema = {
+  typeDefs: {},
+  resolverClasses: [
+    /* RESOLVER CLASSES */
+    ...TwinStateResolvers,
+    ...TwinControlResolvers,
+    ...TwinLifecycleResolvers,
+    ...TwinJournalResolvers
+  ],
+  directives: {}
+}

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

@@ -0,0 +1,3 @@
+import { TwinControlMutation } from './twin-control-mutation.js'
+
+export const resolvers = [TwinControlMutation]

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

@@ -0,0 +1,41 @@
+import { Arg, Mutation, Resolver } from 'type-graphql'
+
+import { ScalarObject } from '@things-factory/shell'
+
+import { TwinEngine } from '../../engine/index.js'
+
+/*
+ * 트윈 Command·Scenario 채널 — 상향 mutation.
+ * Command: runtime.dispatch(행위). Scenario: runtime.scenario.load/start/pause(예측 자극).
+ * (State 하향은 twin-state subscription. tick 은 워커.)
+ */
+@Resolver()
+export class TwinControlMutation {
+  /** Command 채널 — 오더 hold/resume/release 등. 커널 dispatch 로 위임, ack 반환. */
+  @Mutation(returns => Boolean, { description: 'dispatch a twin command (order.hold/resume/release …)' })
+  async dispatchTwinCommand(
+    @Arg('instanceId') instanceId: string,
+    @Arg('command', type => ScalarObject) command: any
+  ): Promise<boolean> {
+    const runtime = TwinEngine.runtime(instanceId)
+    if (!runtime) return false
+    const ack = runtime.dispatch(command)
+    return !!ack?.accepted
+  }
+
+  /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause). */
+  @Mutation(returns => Boolean, { description: 'control twin scenario (load|start|pause)' })
+  async controlTwinScenario(
+    @Arg('instanceId') instanceId: string,
+    @Arg('action') action: string,
+    @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any
+  ): Promise<boolean> {
+    const runtime = TwinEngine.runtime(instanceId)
+    if (!runtime) return false
+    if (action === 'load' && scenario) runtime.scenario.load(scenario)
+    else if (action === 'start') runtime.scenario.start()
+    else if (action === 'pause') runtime.scenario.pause()
+    else return false
+    return true
+  }
+}

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

@@ -0,0 +1,3 @@
+import { TwinEvent } from './twin-event.js'
+
+export const entities = [TwinEvent]

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

@@ -0,0 +1,55 @@
+import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'
+import { ObjectType, Field, ID, Int } from 'type-graphql'
+
+import { Domain, ScalarObject } from '@things-factory/shell'
+
+/*
+ * TwinEvent — append-only 트윈 이벤트 저널(EPCIS 이벤트 + 운영 델타).
+ * 커널 EventJournal 의 영속 대응 — 상태=이벤트열의 함수(재부팅 시 DB→replay 재구성).
+ * append-only 이므로 updater/deletedAt 없음(이력 CRUD 가 아니라 불변 이벤트 스트림).
+ * payload 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통, DB-specific JSON 타입 금지).
+ * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
+ */
+@Entity()
+@Index('ix_twin_event_0', (e: TwinEvent) => [e.domain, e.instanceId, e.revision], { unique: false })
+@ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
+export class TwinEvent {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the event record.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinEvent) => e.domain)
+  domainId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Twin runtime instance id that emitted the event.' })
+  instanceId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Kernel tenant id carried on the canonical envelope.' })
+  tenantId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Event type: epcis.* | task.status | equipment.status | order.status.' })
+  eventType?: string
+
+  @Column({ type: 'int', nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Monotonic state revision at which the event was emitted.' })
+  revision?: number
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Simulation event time (ISO 8601).' })
+  eventTime?: string
+
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Raw canonical envelope (EPCIS event or operational delta) as JSON.' })
+  payload?: any
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Wall-clock timestamp when the record was persisted.' })
+  createdAt?: Date
+}

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

@@ -0,0 +1,3 @@
+import { TwinInstance } from './twin-instance.js'
+
+export const entities = [TwinInstance]

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

@@ -0,0 +1,55 @@
+import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
+import { ObjectType, Field, ID, Int } from 'type-graphql'
+
+import { Domain, ScalarObject } from '@things-factory/shell'
+
+/*
+ * TwinInstance — 트윈 인스턴스 레지스트리(재부팅 복구의 앵커).
+ * 복구(DB→replay)는 board(마스터 청사진)가 있어야 이벤트를 상태로 되짚을 수 있다 → board·kind 를 영속.
+ * 이벤트(TwinEvent)와 달리 가변(status/revision 갱신) — 인스턴스의 "현재 등록 상태".
+ * board 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).
+ * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
+ */
+@Entity()
+@Index('ix_twin_instance_0', (e: TwinInstance) => [e.domain, e.instanceId], { unique: true })
+@ObjectType({ description: 'Registry of a hosted twin runtime instance — anchors reboot recovery (board + kind).' })
+export class TwinInstance {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the registry record.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinInstance) => e.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'Twin runtime instance id (unique within a domain).' })
+  instanceId: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Domain kernel kind: wms | yms | mes.' })
+  kind?: string
+
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'BoardDef blueprint (nodes/movers) required to replay events into state.' })
+  board?: any
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Lifecycle status: running | stopped.' })
+  status?: string
+
+  @Column({ type: 'int', nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Last persisted state revision observed for this instance.' })
+  revision?: number
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when the instance was first registered.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when the instance registry row was last updated.' })
+  updatedAt?: Date
+}

package/server/service/twin-journal/index.ts

@@ -0,0 +1,3 @@
+import { TwinJournalQuery } from './twin-journal-query.js'
+
+export const resolvers = [TwinJournalQuery]

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

@@ -0,0 +1,49 @@
+import { Between, LessThanOrEqual, MoreThanOrEqual } from 'typeorm'
+import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
+
+import { getRepository, ScalarObject } from '@things-factory/shell'
+
+import { TwinEvent } from '../twin-event/twin-event.js'
+import { TwinEngine } from '../../engine/index.js'
+
+/*
+ * 저널 읽기 채널 — 상향 query.
+ * twinEvents : append-only 이벤트 저널 조회(Ledger/History/Entity360) — instanceId·revision 범위·eventType 필터.
+ * twinReplay : 내구 저널을 replay 해 상태 재구성(재부팅 복구·시간여행) — untilRevision 으로 임의 과거.
+ * (실시간 스트림은 twinState subscription, 명령은 twin-control mutation. 이건 '질의' 표면.)
+ */
+@Resolver()
+export class TwinJournalQuery {
+  @Query(returns => [TwinEvent], {
+    description: 'Read the append-only twin event journal (Ledger / History / audit), filtered and ordered by revision.'
+  })
+  async twinEvents(
+    @Arg('instanceId') instanceId: string,
+    @Arg('fromRevision', type => Int, { nullable: true }) fromRevision: number,
+    @Arg('toRevision', type => Int, { nullable: true }) toRevision: number,
+    @Arg('eventType', { nullable: true }) eventType: string,
+    @Arg('limit', type => Int, { nullable: true }) limit: number,
+    @Ctx() context: ResolverContext
+  ): Promise<TwinEvent[]> {
+    const where: any = { domain: { id: context.state.domain.id }, instanceId }
+    if (eventType) where.eventType = eventType
+    if (fromRevision != null && toRevision != null) where.revision = Between(fromRevision, toRevision)
+    else if (fromRevision != null) where.revision = MoreThanOrEqual(fromRevision)
+    else if (toRevision != null) where.revision = LessThanOrEqual(toRevision)
+
+    /* 최신순(DESC) 기본 — Ledger/recent 뷰. 범위 필터로 시간여행 구간 조회도 가능. */
+    return getRepository(TwinEvent).find({ where, order: { revision: 'DESC' }, take: limit ?? 200 })
+  }
+
+  @Query(returns => ScalarObject, {
+    nullable: true,
+    description: 'Reconstruct twin state from the durable journal (DB → replay). untilRevision for time-travel; omit for latest.'
+  })
+  async twinReplay(
+    @Arg('instanceId') instanceId: string,
+    @Arg('untilRevision', type => Int, { nullable: true }) untilRevision: number,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    return TwinEngine.recover(context.state.domain.id, instanceId, untilRevision ?? undefined)
+  }
+}

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

@@ -0,0 +1,3 @@
+import { TwinLifecycleMutation } from './twin-lifecycle-mutation.js'
+
+export const resolvers = [TwinLifecycleMutation]

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

@@ -0,0 +1,44 @@
+import { Arg, Ctx, Mutation, Query, Resolver } from 'type-graphql'
+
+import { ScalarObject } from '@things-factory/shell'
+
+import { TwinEngine } from '../../engine/index.js'
+
+import type { BoardDef } from '@operato/twin-kernel'
+
+/*
+ * 트윈 인스턴스 생명주기 채널 — 프로비저닝(상향).
+ * State/Command/Scenario 는 이미 running 인 인스턴스를 다루지만, 이 채널은 인스턴스 자체를 만들고/없앤다.
+ * (TwinEngine.start/stop 을 GraphQL 로 노출 — 설계 Tier-1 갭: 커널은 start/stop 을 가졌으나 진입점이 없었다.)
+ * board(BoardDef)=구조, scenario=자극 은 분리 — 여기선 구조만 세운다. 자극은 controlTwinScenario 로.
+ */
+@Resolver()
+export class TwinLifecycleMutation {
+  @Mutation(returns => Boolean, {
+    description: 'Provision and start a twin runtime instance (kind: wms|yms|mes) from a BoardDef, and begin the worker tick.'
+  })
+  async startTwinInstance(
+    @Arg('instanceId') instanceId: string,
+    @Arg('kind') kind: string,
+    @Arg('board', type => ScalarObject) board: any,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    TwinEngine.start(instanceId, context.state.domain.id, kind, board as BoardDef)
+    return true
+  }
+
+  @Mutation(returns => Boolean, {
+    description: 'Stop and dispose a running twin runtime instance by its id.'
+  })
+  async stopTwinInstance(@Arg('instanceId') instanceId: string): Promise<boolean> {
+    await TwinEngine.stop(instanceId)
+    return true
+  }
+
+  @Query(returns => [String], {
+    description: 'List ids of currently running twin runtime instances.'
+  })
+  twinInstances(): string[] {
+    return Object.keys(TwinEngine.instances)
+  }
+}

package/server/service/twin-state/index.ts

@@ -0,0 +1,3 @@
+import { TwinStateSubscription } from './twin-state-subscription.js'
+
+export const resolvers = [TwinStateSubscription]

package/server/service/twin-state/twin-state-subscription.ts

@@ -0,0 +1,53 @@
+import { filter, pipe } from 'graphql-yoga'
+import { Arg, Field, Int, ObjectType, Resolver, Root, Subscription } from 'type-graphql'
+
+import { pubsub, ScalarObject } from '@things-factory/shell'
+
+import { TwinEngine } from '../../engine/index.js'
+
+/* State 채널 메시지 — snapshot | delta | clock 멀티플렉싱(커널 SubscriptionMessage 대응). */
+@ObjectType({ description: 'Twin State channel message multiplexing snapshot | delta | clock.' })
+export class TwinStateMessage {
+  @Field({ description: 'Twin runtime instance id this message belongs to.' })
+  instanceId: string
+
+  @Field({ description: 'Message kind: snapshot | delta | clock.' })
+  kind: string
+
+  @Field(type => Int, { nullable: true, description: 'Monotonic state revision.' })
+  revision?: number
+
+  @Field(type => ScalarObject, { nullable: true, description: 'Payload — snapshot: StateSnapshot / delta: CanonicalEnvelope / clock: { simClockMs }.' })
+  payload?: any
+}
+
+/*
+ * 트윈 State 구독 — state-register/data-resolver 패턴 미러.
+ * 구독 즉시 현재 snapshot 발행(process.nextTick) 후 delta/clock 스트림. instanceId 로 필터.
+ */
+@Resolver()
+export class TwinStateSubscription {
+  @Subscription(returns => TwinStateMessage, {
+    subscribe: ({ args, context }) => {
+      const { instanceId } = args
+
+      /* 구독 순간 현재 상태를 먼저 발행(late 구독자도 snapshot→delta 순서 보장). */
+      process.nextTick(() => {
+        const snap = TwinEngine.snapshot(instanceId)
+        if (snap) {
+          pubsub.publish('twin-state', {
+            twinState: { instanceId, kind: 'snapshot', revision: snap.revision, payload: snap }
+          })
+        }
+      })
+
+      return pipe(
+        pubsub.subscribe('twin-state'),
+        filter((payload: { twinState: TwinStateMessage }) => payload.twinState.instanceId === instanceId)
+      )
+    }
+  })
+  twinState(@Root() payload: { twinState: TwinStateMessage }, @Arg('instanceId') instanceId: string): TwinStateMessage {
+    return payload.twinState
+  }
+}

package/server/types/global.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Global type definitions for the headless-twin module.
+ */
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+
+declare global {
+  /**
+   * GraphQL Resolver Context — available in every @Ctx() decorated parameter.
+   */
+  interface ResolverContext {
+    state: {
+      domain: Domain
+      user: User
+      [key: string]: any
+    }
+    [key: string]: any
+  }
+}
+
+export {}

package/things-factory.config.js

@@ -0,0 +1,2 @@
+/* headless-twin 은 서버-only(헤드리스) 모듈 — 클라이언트/라우트 없음. */
+export default {}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig-base.json",
+  "compilerOptions": {
+    "outDir": "./dist-server",
+    "baseUrl": "./",
+    "skipLibCheck": true
+  },
+  "include": ["./server/**/*"],
+  "exclude": ["**/*.spec.ts"]
+}