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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@things-factory/headless-twin",
+  "version": "10.0.0-zeta.7",
+  "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.3",
+    "@things-factory/env": "^10.0.0-zeta.1",
+    "@things-factory/shell": "^10.0.0-zeta.3"
+  },
+  "gitHead": "937be2e53a88f68474ab493dad86b018b3901b81"
+}

package/server/engine/index.ts

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

package/server/engine/twin-engine.ts

@@ -0,0 +1,95 @@
+/*
+ * 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)만 얇게 래핑.
+ * (설계 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 type { TwinKernel, BoardDef, SubscriptionMessage, TwinRuntime as TwinRuntimeType } from '@operato/twin-kernel'
+
+/* 커널 런타임 로드 — CJS 번들(dist-cjs). 타입은 위 import type 로. */
+const { WmsKernel, YmsKernel, MesKernel, TwinRuntime } = require('@operato/twin-kernel')
+
+const KERNELS: Record<string, any> = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel }
+
+interface TwinInstance {
+  id: string
+  domainId: string
+  runtime: TwinRuntimeType
+  unsub: () => void
+  timer?: any
+}
+
+export class TwinEngine {
+  static instances: Record<string, TwinInstance> = {}
+  static TICK_MS = 1000
+
+  /** 부팅 훅 — 영속 인스턴스 복구(DB→replay)는 향후. 지금은 명시 start 로 인스턴스 생성. */
+  static async bootstrap(): Promise<void> {}
+
+  /** 트윈 인스턴스 시작 — 커널 생성 + 보드 로드 + State 스트림 브리지 + 워커 tick. */
+  static start(id: string, domainId: string, kind: string, board: BoardDef): TwinInstance {
+    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 저장. 재부팅 복구는 DB→replay(향후). */
+      if (msg.kind === 'delta') this.persist(domainId, id, msg).catch(err => console.error('twin persist fail', err))
+    })
+
+    /* subscribe 는 RuntimeSubscription({ unsubscribe() }) 반환 → () => void 로 감쌈. */
+    const inst: TwinInstance = { id, domainId, runtime, unsub: () => sub.unsubscribe() }
+    this.instances[id] = inst
+
+    /* 워커 tick — 스켈레톤은 setInterval(메인 루프). 긴 시뮬 오프-루프(worker thread)는 스케일 하드닝(향후, §host 경계). */
+    inst.timer = setInterval(() => runtime.tick(this.TICK_MS), this.TICK_MS)
+    return inst
+  }
+
+  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
+      })
+    )
+  }
+
+  static stop(id: string): void {
+    const i = this.instances[id]
+    if (!i) return
+    clearInterval(i.timer)
+    i.unsub()
+    delete this.instances[id]
+  }
+
+  static runtime(id: string): TwinRuntimeType | undefined {
+    return this.instances[id]?.runtime
+  }
+
+  /** 현재 전체 스냅샷(구독 즉시 발행·resync 용). */
+  static snapshot(id: string): any {
+    return this.instances[id]?.runtime.resync()
+  }
+}

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,25 @@
+/* EXPORT ENTITY TYPES */
+export * from './twin-event/twin-event.js'
+export * from './twin-state/twin-state-subscription.js'
+
+/* IMPORT ENTITIES AND RESOLVERS */
+import { entities as TwinEventEntities } from './twin-event/index.js'
+import { resolvers as TwinStateResolvers } from './twin-state/index.js'
+import { resolvers as TwinControlResolvers } from './twin-control/index.js'
+
+export const entities = [
+  /* ENTITIES */
+  ...TwinEventEntities
+]
+
+export const subscribers = []
+
+export const schema = {
+  typeDefs: {},
+  resolverClasses: [
+    /* RESOLVER CLASSES */
+    ...TwinStateResolvers,
+    ...TwinControlResolvers
+  ],
+  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-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/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"]
+}