@things-factory/headless-twin 10.1.277 → 10.1.279

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

@@ -1,148 +0,0 @@
-import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
-import { ObjectType, Field, ID } from 'type-graphql'
-
-import { Domain, ScalarObject } from '@things-factory/shell'
-
-/*
- * TwinSpace — 테넌트 1급 공간(Site) 정의(ADR-0016). 트윈보다 먼저 세우는 몰입의 무대.
- * 공간이 보이는 방식(레이아웃·배경·영역)은 정규화됨: TwinSpaceRepresentation(map|image|model —
- *   이미지 배경은 attachment-base 참조 `config.imageUrl`) + TwinSpaceArea. 인스턴스는 model.spaceId 로 바인딩.
- *  - geo = 사이트 지오레퍼런스, primaryRepresentationId = 홈/모니터 대표 표현.
- *  - content(simple-json) 는 정규화 이전 레거시 단일 blob(@deprecated, P6 제거) — 신규 저작은 representation/area 로.
- * (CLAUDE.md: 모든 @ObjectType/@Field 영문 description 필수.)
- */
-@Entity()
-@Index('ix_twin_space_0', (e: TwinSpace) => [e.domain, e.spaceId], { unique: true })
-@ObjectType({ description: 'A tenant-level twin Space (Site) — the shared spatial stage set up before instances; its layout, backdrop and areas are normalized into representations (image backdrops via attachment-base) and areas.' })
-export class TwinSpace {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID, { description: 'Unique identifier of the space record.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
-  domain?: Domain
-
-  @RelationId((e: TwinSpace) => e.domain)
-  domainId?: string
-
-  @Column()
-  @Field({ description: 'Space id (unique within a domain).' })
-  spaceId: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Human-readable space name.' })
-  name?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Space description.' })
-  description?: string
-
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Site georeference { lat, lon, rotation } — pins the design frame to the earth so every representation lands in the same place. `rotation` is degrees clockwise from true north (bearing convention: 0 = north, 90 = east) by which the design frame is turned.' })
-  geo?: any
-
-  /*
-   * 설계 좌표계의 범위 — **미터**. `geo` 와 한 쌍이다.
-   *
-   * 구역(TwinArea.layout)은 표현 중립 설계 좌표 `{x, y, w, h}` 로 놓인다. 그 좌표가 어디까지인지를
-   * 이 둘이 정하고, `geo` 가 그것을 지구에 붙인다 — 지도로 보든 도면 이미지로 보든 보드로 보든
-   * 구역이 같은 자리에 있어야 하므로, 범위도 지오레퍼런스도 **표현이 아니라 공간**이 갖는다.
-   *
-   *   설계 좌표 (x, y) ──[extentX/extentY 로 중심 이동]──▶ 미터 오프셋 ──[geo]──▶ 위경도
-   *
-   * `width`/`depth` 라 부르지 않는 이유: 컴포넌트 속성의 `depth` 는 높이 축(z)이다. 같은 화면에서
-   * 한 낱말이 두 축을 가리키면 읽는 사람이 매번 어느 쪽인지 물어야 한다.
-   * 단위 필드는 두지 않는다 — 미터로 고정이고, 있으면 "단위를 지원한다" 는 거짓 신호가 된다.
-   */
-  @Column({ type: 'float', nullable: true })
-  @Field({ nullable: true, description: 'Extent of the design frame along the east-west axis, in metres. Area layouts are placed within this frame.' })
-  extentX?: number
-
-  @Column({ type: 'float', nullable: true })
-  @Field({ nullable: true, description: 'Extent of the design frame along the north-south axis, in metres. Area layouts are placed within this frame.' })
-  extentY?: number
-
-  /**
-   * 이 현장의 시각 기준 — IANA 이름(`'America/Tijuana'`).
-   *
-   * **테넌트가 아니라 공간이 갖는다.** 한 테넌트가 Rosarito(태평양)와 한국 공장을 함께 가질 수 있고,
-   * 테넌트 단위(`Domain.timezone`)로 두면 둘 중 하나는 반드시 틀린다. 교대가 "06시" 라고 할 때 그것이
-   * 어느 06시인가는 **물리 현장의 성질**이다.
-   *
-   * 오프셋 숫자가 아니라 이름으로 둔다: 숫자로는 일광절약시간을 표현할 수 없고, 나중에 절대 구간
-   * (표준 `StartDateTime`)으로 옮길 때도 이름이 있어야 계산할 수 있다.
-   */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'IANA time zone of this physical site (e.g. America/Tijuana) — the base for reading shift times. Belongs to the space, not the tenant, because one tenant can run plants in different zones.' })
-  timezone?: string
-
-  /**
-   * **이 현장이 언제 도나** — 표준 `WorkCalendarEntry`(복수). 휴일 · 주말 · 정기보수가 여기 든다.
-   *
-   * ── 왜 공간에 있나 (2026-09-07) ──────────────────────────────────────────
-   * 이 칸이 없던 동안 설비와 사람만 달력을 가질 수 있었다. 그래서 **현장이 언제 쉬는지가 어디에도
-   * 없었고**, 계획 조업 시간이 「재기 시작한 뒤 흐른 시간 전부」였다 — 주말도 야간도 휴일도 계획 조업으로
-   * 세었다. [산술] 8시간 × 주5일이면 168시간 중 40시간이 조업이니 그 수가 4.2배 크다.
-   *
-   * 시간대와 같은 축이라 같은 자리에 둔다. 「이 현장의 06:00 이 언제인가」와 「이 현장이 언제 도나」는
-   * 둘 다 현장이 갖는 값이고, 테넌트가 아니다 — 한 테넌트가 다른 시간대·다른 조업일의 공장을 함께 가진다.
-   *
-   * `withSpaceTimeBase` 가 이 값을 모델에 얹고, 거기서 OEE 누적기가 계획 정지를 낸다. 얹는 자리를
-   * 시간대와 하나로 둔 이유는 **한쪽만 채워진 상태**를 만들지 않기 위해서다.
-   *
-   * 없으면 아무것도 가정하지 않는다 — 종일 가동으로 보는 것은 「제약이 없다」가 아니라 「선언되지
-   * 않았다」이고, 그 사실은 세어져야 한다(안 그러면 사람이 수를 되살리려고 아무 달력이나 채운다).
-   */
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, {
-    nullable: true,
-    description:
-      'When this site runs — standard WorkCalendarEntry list (holidays, weekends, planned maintenance). Absent means undeclared, not unrestricted: planned busy time then counts the whole window.'
-  })
-  workCalendar?: any
-
-  /**
-   * 현장의 **우편 주소** — 사람이 읽고 서류에 적는 값.
-   *
-   * ── 왜 좌표와 따로 두나 (2026-09-07) ────────────────────────────────────
-   * `geo` 는 도면을 지구에 붙이는 값이고 화면이 쓴다. 주소는 **사람과 서류의 값**이다 — 납품·통관·
-   * 감사에 그 문자열이 그대로 들어가고, 좌표에서 되돌려 만들 수 없다(같은 좌표에 여러 주소가 있고
-   * 동·호가 좌표에 없다).
-   *
-   * 고객이 준 것을 그대로 적는다. 우편번호·동·호를 우리가 지어내거나 좌표에서 유추하지 않는다.
-   */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Postal address of this site as the customer states it. Kept apart from `geo`: a floor or unit number has no coordinate, and paperwork carries this string verbatim.' })
-  address?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Id of the primary representation shown on the home/monitor.' })
-  primaryRepresentationId?: string
-
-  /**
-   * 이 **현장**의 로컬 선언 겹 — 요금처럼 **트윈이 아니라 현장이 정하는 수**.
-   *
-   * ── 왜 트윈에 두면 안 되나 (2026-08-18) ────────────────────────────────────
-   * 요금 단가·통화는 그 현장의 계약이므로, 같은 수전을 보는 EMS 트윈이 둘이면 **같은 값을 두 번**
-   * 선언해야 했다. 두 번 적는 값은 반드시 갈라진다(하나만 고치는 날이 온다) — 그때 두 트윈이 다른
-   * 금액을 말하고, 어느 쪽이 맞는지 화면으로는 알 수 없다.
-   *
-   * 적용 순서는 **현장 먼저, 트윈이 나중**이다. 더 좁은 선언이 이긴다 — 한 현장 안에서 특정 트윈만
-   * 다른 값으로 실험하는 일이 있고(예: 인상된 단가로 what-if), 그때 현장 값을 고치게 만들면 나머지
-   * 트윈이 함께 흔들린다.
-   *
-   * 모양은 트윈 겹과 같다(`LocalDeclaration`) — 같은 규칙(검사·기억·철회)을 두 벌로 만들지 않는다.
-   */
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: "Locally-declared values that belong to this facility rather than to one twin (tariff, currency). Applied to every twin in the space before the twin's own declarations, which win when both name the same property." })
-  localDeclarations?: any
-
-  @CreateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when the space was created.' })
-  createdAt?: Date
-
-  @UpdateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when the space was last updated.' })
-  updatedAt?: Date
-}

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

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

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

@@ -1,62 +0,0 @@
-import { filter, pipe } from 'graphql-yoga'
-import { Arg, Field, Int, ObjectType, Resolver, Root, Subscription } from 'type-graphql'
-
-import { assertDomainSubscribeAllowed, pubsub, ScalarObject } from '@things-factory/shell'
-
-import { TwinEngine } from '../../engine/index.js'
-import { TWIN_STATE_TOPIC, twinStateFilter, twinStatePayload, type TwinStatePayload } from '../../engine/twin-state-channel.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 스트림.
- *
- * The tenant is asked while streaming, not only at subscribe time (2026-09-24). Ownership used to be
- * checked once and the stream filtered on instanceId alone; the same id in two tenants is the normal
- * case (`runtime-key.ts`), so other tenants' deltas came through, and the snapshot sent to a new
- * subscriber reached every tenant subscribed to that id. Messages now carry their domain and the filter
- * compares it (`engine/twin-state-channel.ts`). A twin the caller does not own is refused rather than
- * given an empty stream — an empty stream cannot tell "nothing changed" from "you may not see this"
- * (shell's `data` throws too).
- */
-@Resolver()
-export class TwinStateSubscription {
-  @Subscription(returns => TwinStateMessage, {
-    subscribe: async ({ args, context }) => {
-      const { instanceId } = args
-      const { domain, user } = (context as any)?.state ?? {}
-      await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
-
-      /* One refusal for both cases, so the answer does not reveal whether another tenant has such a twin. */
-      if (!TwinEngine.owns(domain.id, instanceId)) throw new Error(`twin instance not running in this tenant: ${instanceId}`)
-
-      /* Current state first (a late subscriber still sees snapshot → delta). It reaches this tenant's subscribers only. */
-      process.nextTick(() => {
-        const snap = TwinEngine.snapshot(domain.id, instanceId)
-        if (snap) {
-          pubsub.publish(TWIN_STATE_TOPIC, twinStatePayload(domain.id, { instanceId, kind: 'snapshot', revision: snap.revision, payload: snap }))
-        }
-      })
-
-      return pipe(pubsub.subscribe(TWIN_STATE_TOPIC), filter(twinStateFilter(domain.id, instanceId)))
-    }
-  })
-  twinState(@Root() payload: TwinStatePayload, @Arg('instanceId') instanceId: string): TwinStateMessage {
-    return payload.twinState as TwinStateMessage
-  }
-}

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

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

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

@@ -1,96 +0,0 @@
-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'
-import { User } from '@things-factory/auth-base'
-import { modelColumnTransformer } from '../../engine/model-vocabulary.js'
-
-/*
- * TwinStructure — **한 트윈이 거쳐 온 공장 구조들.** 리비전 하나가 그 시절의 공장이다.
- *
- * ── 왜 필요한가: 역사를 잃거나 거짓말을 하거나 ──────────────────────────────
- * 공장은 바뀐다. 도장 부스를 넷 더 놓고, 라인 하나를 닫는다. 그런데 지금까지는 구조 서명이 바뀌면
- * **그 트윈의 저널을 통째로 지우는 것**이 유일한 길이었다. 안 지우면 옛 이벤트를 새 공장에 대고
- * 계산하게 되어 이력이 거짓말을 하기 때문이다 — 부스가 둘이던 시절의 사실을 여섯 개짜리 공장에 계산하면
- * 그때 없던 부스에서 일이 있었던 것처럼 보인다.
- *
- * 그래서 선택지가 둘뿐이었다: **역사를 잃거나, 거짓말을 하거나.**
- *
- * 셋째 길이 이 표다. 이벤트가 `structureRev` 로 자기 구조를 달고 다니고, 재생은 구조가 바뀌는
- * 지점에서 전환한 뒤 이어서 계산한다(`replaySegments`). 이력은 "그때 그 공장의 사실" 로 계속 읽힌다.
- *
- * ── 왜 model 를 통째로 담나 ─────────────────────────────────────────────────
- * 재생하려면 **그때의 토폴로지 전체**가 필요하다. 차이(diff)만 담으면 리비전 1부터 다시 계산해 쌓아야
- * 하고, 그 재계산 자체가 또 하나의 규칙이 되어 어긋난다. 구조는 이벤트에 비해 드물게 바뀌므로
- * 스냅샷을 통째로 두는 편이 싸고 정직하다(보드 이력 `BoardHistory` 와 같은 선택).
- *
- * ── audit 컬럼을 다 두지 않는 이유 ──────────────────────────────────────────
- * 리비전은 **한 번 쓰이면 바뀌지 않는다** — 그 시절의 사실이라 고칠 수가 없다. 그래서 updater·
- * deletedAt 이 없다(TwinEvent 와 같은 규율). 대신 **누가 구조를 바꿨는지**는 남긴다.
- *
- * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
- */
-@Entity()
-@Index('ix_twin_structure_0', (e: TwinStructure) => [e.domain, e.instanceId, e.rev], { unique: true })
-@ObjectType({
-  description:
-    'One structural revision of a twin — the plant as it stood for a stretch of its journal. Events carry the revision they were produced under, so history can be replayed against the structure that was actually in force instead of being deleted when the plant changes.'
-})
-export class TwinStructure {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID, { description: 'Unique identifier of the structure revision record.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
-  domain?: Domain
-
-  @RelationId((e: TwinStructure) => e.domain)
-  domainId?: string
-
-  @Column()
-  @Field({ description: 'Twin runtime instance this structure belongs to.' })
-  instanceId: string
-
-  /**
-   * 리비전 번호 — 1부터. 이벤트의 `structureRev` 가 이것을 가리킨다.
-   *
-   * 0 을 안 쓰는 이유: 컬럼이 없던 시절의 행은 `structureRev` 가 비어 있고, 그 행들은 **가장 오래된
-   * 리비전**에 속한다. 0 을 유효 번호로 쓰면 "모름" 과 "1번 구조" 가 같은 값이 된다.
-   */
-  @Column({ type: 'int' })
-  @Field(type => Int, { description: 'Revision number, starting at 1. Events reference it via structureRev; absent on rows written before structure revisions existed, which belong to the oldest revision.' })
-  rev: number
-
-  /**
-   * 구조 서명 — 이 리비전이 앞 리비전과 **정말 다른지** 판정한 근거.
-   *
-   * 서명이 같으면 새 리비전을 만들지 않는다. 프로비저닝은 자주 다시 도는데(부팅마다) 그때마다
-   * 리비전이 하나씩 늘면 이력이 뜻 없는 마디로 잘게 쪼개진다.
-   */
-  @Column({ length: 64 })
-  @Field({ description: 'Short hash of the structural signature (locations + equipment). A re-provision with the same signature does not create a new revision — otherwise every reboot would slice the history into meaningless segments.' })
-  signature: string
-
-  /* 읽을 때 어휘 세대를 흡수한다 — 옛 리비전의 모델로 지문을 다시 계산할 때 빈 공장으로 읽히면
-     구조 변경 감지가 죽는다(`engine/model-vocabulary.ts`). */
-  @Column({ type: 'simple-json', transformer: modelColumnTransformer })
-  @Field(type => ScalarObject, { description: 'The full TwinModelDef as it stood for this revision. Stored whole rather than as a diff: replay needs the entire topology, and rebuilding it from diffs would be a second rule that can drift.' })
-  model: any
-
-  /** 왜 바뀌었나 — 사람이 남기는 한 줄. 없을 수 있다(자동 프로비저닝은 이유를 모른다). */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Why the structure changed — a human note, absent for automatic provisioning.' })
-  comment?: string
-
-  @ManyToOne(type => User, { nullable: true })
-  @Field(type => User, { nullable: true, description: 'Who changed the structure, when known.' })
-  creator?: User
-
-  @RelationId((e: TwinStructure) => e.creator)
-  creatorId?: string
-
-  @CreateDateColumn()
-  @Field({ nullable: true, description: 'When this revision took effect.' })
-  createdAt?: Date
-}

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

@@ -1,162 +0,0 @@
-/*
- * **이 사건은 무엇에 대한 것인가** — 사건 하나에서 가리키는 대상들을 뽑는다.
- *
- * ── 왜 필요한가 (2026-08-27 실측) ───────────────────────────────────────────
- * 360 화면이 「이 대상의 이력」을 묻는다. 그 조회가 64초다. 대상으로 걸러 시각순으로 정렬하는 목차가
- * 없기 때문이고, 목차를 얹어도 풀리지 않는다.
- *
- *   부분일치(지금 화면)      63.998초   앞에 와일드카드가 붙어 목차를 쓸 수 없다
- *   정확일치로 바꾸면        67.316초 · 0건   품목 하나에 로트가 여럿이라 성립하지 않는다
- *   앞부분 범위로 바꾸면     68.402초   목차는 쓰지만 정렬 때문에 맞는 행을 다 가져온다
- *
- * 저장된 식별자에 품목과 로트가 한 문자열로 붙어 있는 것이 그 원인이다.
- *
- *   https://seunghwa.net/class/product-M0000618-lot-L2604100071
- *
- * 그래서 문자열을 자르는 대신 **대상마다 한 줄**을 적는다. 같은 사건이 품목과 로트를 함께 가리키면
- * 두 줄이다. 자를 규칙이 필요 없다 — 넣는 쪽이 이미 둘을 안다.
- *
- * ── 왜 「뜻이 달라지는 키 칸」이 아닌가 ─────────────────────────────────────
- * `key01~05` 처럼 칸을 두고 사건 종류에 따라 뜻을 달리 쓰는 방식을 **이 표에는** 쓰지 않는다.
- *
- * 그 방식 자체가 틀린 것은 아니다. 데이터셋마다 정의가 따로 있는 프레임워크에서는 합리적이다 — 읽는
- * 쪽이 그 정의를 보고 해석한다. 우리 저널은 표 하나를 화면 여럿이 읽고 볼 정의가 없다. 그래서
- * 「M0000438 을 찾아 줘」가 어떤 줄에서는 품목, 다른 줄에서는 오더가 되고, 묻는 쪽이 사건 종류마다
- * 어느 칸에 무엇이 들어가는지 외워야 한다.
- *
- * **종류를 값으로 밝힌다.** 그러면 읽는 쪽이 사건 종류표를 들고 있지 않아도 된다.
- *
- * ── 왜 순수 모듈인가 ────────────────────────────────────────────────────────
- * 기록 경로에서 불리므로 DB·데코레이터를 알지 않는다. 그래야 테스트가 값으로 확인할 수 있다
- * (`twin-event-keys` 와 같은 이유다).
- *
- * 설계: `operato-twin/design/plans/read-models.md`
- */
-import { twinEventKeys } from '../twin-event/twin-event-keys.js'
-
-/**
- * 대상의 종류 — **닫힌 목록**이다.
- *
- * 열어 두면 넣는 쪽마다 다른 이름을 쓰게 되고(설비를 세 가지 이름으로 부르는 식), 그러면 조회가
- * 어느 이름으로 물어야 하는지 알 수 없다. 늘려야 하면 이 목록에 더한다.
- *
- *   item        선언된 품목. 로트 여럿이 같은 품목을 가리킨다
- *   lot         개체 하나. 저장된 식별자 그대로다
- *   order       오더
- *   location    자리
- *   equipment   설비
- *   task        작업
- *   transaction 거래(PO/SO/생산오더) — 오더와 다르다. 전에는 오더 칸에 섞여 들어와 한 오더의
- *               이력이 두 쪽으로 갈라졌다(2026-09-05)
- */
-export const SUBJECT_KINDS = ['item', 'lot', 'order', 'location', 'equipment', 'task', 'transaction'] as const
-export type SubjectKind = (typeof SUBJECT_KINDS)[number]
-
-export interface EventSubject {
-  kind: SubjectKind
-  id: string
-}
-
-/**
- * 개체 식별자에서 **선언된 품목**을 찾아 주는 함수 — 부르는 쪽이 넘긴다.
- *
- * 이 모듈이 문자열을 자르지 않는 이유는 그 규칙이 연결된 시스템마다 다르기 때문이다. 어느 부호가
- * 로트를 가리키는지 커널 계약이 정한 적이 없고, chef 의 `-lot-` 을 여기에 굳히면 이 파일이 그
- * 시스템 위에 서게 된다(`item-ref.ts` 가 같은 판단을 적어 두었다).
- *
- * 그래서 판정은 **그 트윈의 선언**과 견주어 하고(`resolveByDeclaration`), 그 선언을 아는 것은
- * 부르는 쪽이다. 답하지 못하면 `undefined` — 그때는 품목 줄을 만들지 않는다. 짐작으로 이으면 남의
- * 품목 이력에 이 사건이 섞인다.
- */
-export type ItemResolver = (epc: string) => string | null | undefined
-
-/** 컬럼 길이 상한 — `twin-event-keys` 와 같은 값이다(같은 표에 나란히 서는 값이므로). */
-const MAX_ID = 255
-
-function put(out: EventSubject[], kind: SubjectKind, raw: unknown): void {
-  if (raw === undefined || raw === null) return
-  const id = String(raw).trim()
-  if (!id || id.length > MAX_ID) return
-  /* 같은 대상을 두 번 적지 않는다 — 사건 하나에 같은 자리가 두 번 실려 올 수 있다. */
-  if (out.some(s => s.kind === kind && s.id === id)) return
-  out.push({ kind, id })
-}
-
-/**
- * 사건 하나가 가리키는 대상들 — 없으면 빈 배열이다.
- *
- * 승격된 검색 키(`twinEventKeys`)를 그대로 쓴다. 그 함수가 이미 사건 종류별로 어디에서 값을 꺼낼지
- * 알고 있으므로, 여기서 다시 판단하면 두 곳이 어긋난다.
- *
- * **작업은 승격 키에 없어서 봉투에서 직접 읽는다.** 승격 컬럼을 늘리는 것은 이 작업의 범위가 아니다
- * (그것이 바로 이 파생 표로 대신하려는 일이다).
- */
-export function subjectsOf(envelope: any, opts?: { itemOf?: ItemResolver }): EventSubject[] {
-  const keys = twinEventKeys(envelope)
-  const out: EventSubject[] = []
-
-  /*
-   * ── 개체로 온 것과 클래스로 온 것을 갈라 적는다 (2026-08-27 실측) ────────────
-   *
-   * `epcOf` 는 셋을 한 칸에 담는다 — `epcList[0]` · `parentID` · `quantityList[0].epcClass`.
-   * 승격 컬럼이 하나라서 그렇게 되어 있고, 그 칸으로는 「개체인가 클래스인가」를 알 수 없다.
-   *
-   * 실측한 chef 의 사건 하나가 그 경우다. 물건을 개체로 세지 않고 무게로 담는 현장이라 `epcList` 가
-   * 비어 있고 `quantityList` 에 클래스가 있다.
-   *
-   *   epcList     []
-   *   quantityList [{ epcClass: 'https://…/product-M0000879', quantity: 11797.6, uom: 'KGM' }]
-   *
-   * 그것을 로트로 적으면 뜻이 틀린다 — 개체가 아니라 품목이다. 이 표는 종류를 값으로 밝히므로
-   * 갈라 적을 수 있다.
-   */
-  const d = envelope?.data ?? envelope ?? {}
-  const instanceEpc = d.epcList?.[0] ?? d.parentID
-  const classEpc = d.quantityList?.[0]?.epcClass
-
-  if (instanceEpc) {
-    /* 개체는 저장된 식별자 그대로다 — 자르지 않는다. */
-    put(out, 'lot', instanceEpc)
-    /*
-     * 품목은 선언과 견주어 찾는다. 답이 개체 식별자와 같으면 품목을 찾지 못한 것이므로 줄을 만들지
-     * 않는다 — `itemRefOf` 는 URI 세계에서 문자열을 그대로 돌려주기 때문에 그 값이 그대로 올 수 있다.
-     */
-    const item = opts?.itemOf?.(String(instanceEpc))
-    if (item && item !== instanceEpc) put(out, 'item', item)
-  }
-  if (classEpc) {
-    /*
-     * 클래스로 온 것은 개체 줄을 만들지 않는다 — 그 사건에 개체가 없다. 품목 줄만 만든다.
-     *
-     * 선언과 견주어 품목을 찾고, 찾지 못하면 클래스 문자열을 그대로 품목으로 쓴다. 클래스는 이미 품목을
-     * 가리키는 값이므로 그것이 짐작이 아니다(개체 식별자를 그대로 품목으로 쓰는 것과 다르다).
-     */
-    const item = opts?.itemOf?.(String(classEpc)) ?? null
-    put(out, 'item', item || classEpc)
-  }
-  put(out, 'order', keys.orderId)
-  /*
-   * 거래는 오더가 아니다 — 갈라 적는다. 합쳐 적으면 EPCIS 사건의 GDTI 가 오더 이름으로 앉고,
-   * 그러면 한 오더의 이력이 두 쪽이 된다(`twin-event-keys.ts` 의 그 실측).
-   */
-  put(out, 'transaction', keys.bizTransaction)
-  put(out, 'location', keys.locationId)
-  put(out, 'equipment', keys.moverId)
-
-  const data = envelope?.data
-  put(out, 'task', data?.taskId)
-  /*
-   * ── 작업이 오간 두 자리도 적는다 ────────────────────────────────────────────
-   *
-   * 승격 컬럼(`locationId`)은 EPCIS 자리만 담는다(`readPoint` · `bizLocation` · `location`). 작업이
-   * A 에서 B 로 갈 때 그 컬럼에는 **둘 중 하나만** 넣을 수 있어서 아무것도 넣지 않는다.
-   *
-   * 여기서는 둘 다 적는다. 이것이 승격 컬럼과의 어긋남이 아니라 **이 표가 할 수 있는 일**이다 —
-   * 자리 하나에 줄 하나이므로 두 자리를 함께 담는다. 「그 자리에서 무슨 일이 있었나」를 묻는 화면은
-   * 출발지와 도착지를 둘 다 그 자리의 사건으로 본다.
-   */
-  put(out, 'location', data?.fromNode)
-  put(out, 'location', data?.toNode)
-
-  return out
-}

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

@@ -1,10 +0,0 @@
-import { TwinSubjectEvent } from './twin-subject-event.js'
-import { TwinSubjectQuery, TwinSubjectMutation } from './twin-subject-query.js'
-
-export const entities = [TwinSubjectEvent]
-export const resolvers = [TwinSubjectQuery, TwinSubjectMutation]
-export { TwinSubjectEvent, TwinSubjectQuery, TwinSubjectMutation }
-export * from './event-subjects.js'
-export * from './item-resolver.js'
-export * from './twin-subject-writer.js'
-export * from './twin-subject-backfill.js'

package/server/service/twin-subject/item-resolver.ts

@@ -1,92 +0,0 @@
-import { itemRefOf, resolveByDeclaration } from '../twin-model/item-ref.js'
-import type { ItemResolver } from './event-subjects.js'
-
-/*
- * **개체 식별자 → 선언된 품목** — 대상별 사건 목록에 품목 줄을 적기 위한 것.
- *
- * ── 왜 문자열을 자르지 않나 ─────────────────────────────────────────────────
- * 저장된 식별자에 품목과 로트가 붙어 있다.
- *
- *   https://seunghwa.net/class/product-M0000438-lot-L2403090386
- *
- * 여기서 품목을 꺼내려면 `-lot-` 이 로트를 가리킨다는 것을 알아야 하는데, 그 부호는 연결된 시스템마다
- * 다르고 커널 계약이 정한 적이 없다. 한 시스템의 관습을 규칙으로 굳히면 이 코드가 그 시스템 위에 서게
- * 된다(`item-ref.ts` 가 같은 판단을 적어 두었다).
- *
- * 그래서 **그 트윈의 선언과 견주어** 판정한다. 선언된 품목 중 이 식별자가 가리키는 것을 찾고, 후보가
- * 둘 이상이면 답하지 않는다 — 짐작으로 이으면 남의 품목 이력에 이 사건이 섞인다.
- *
- * ── 왜 기억해 두나 ──────────────────────────────────────────────────────────
- * 사건마다 부르는 함수다(초당 130건). 같은 개체 식별자가 계속 되풀어 오므로, 한 번 판정한 것은 기억해
- * 둔다. 트윈의 선언이 바뀌면 그 기억을 버려야 하므로 **선언의 개수와 첫 항목으로 세대**를 만든다 —
- * 선언이 바뀌면 세대가 달라져 다시 판정한다.
- */
-
-/** 트윈마다 기억해 둔 판정 — 세대가 바뀌면 버린다. */
-const memo = new Map<string, { generation: string; declared: Map<string, string>; seen: Map<string, string | null> }>()
-
-/** 한 트윈이 기억할 개체 식별자 수 상한 — 넘으면 비우고 다시 채운다(무한히 자라지 않게). */
-const MEMO_LIMIT = 20_000
-
-/**
- * 선언된 품목의 식별자들을 모은다 — 트윈 모델이 말하는 것만.
- *
- * `materialDefinitions` 가 이 트윈이 다루는 품목의 선언이다. 그 항목의 `id` 와, 연결된 시스템의
- * 어휘로 이어 둔 값(`binding`)을 함께 후보로 둔다 — 개체 식별자는 후자를 앞부분으로 갖는다.
- */
-function declaredItems(model: any): Map<string, string> {
-  const out = new Map<string, string>()
-  const defs = model?.productionSpec?.materialDefinitions ?? model?.materialDefinitions
-  if (!Array.isArray(defs)) return out
-  for (const d of defs) {
-    const id = String(d?.id ?? '').trim()
-    if (!id) continue
-    out.set(id, id)
-    const binding = d?.binding
-    const bound = typeof binding === 'string' ? binding : binding?.epcClass ?? binding?.id
-    const b = String(bound ?? '').trim()
-    if (b) out.set(b, id)
-  }
-  return out
-}
-
-/** 선언이 바뀌었는지 값싸게 가리는 표식 — 개수와 첫·끝 항목이면 실제 변경을 잡는다. */
-function generationOf(declared: Map<string, string>): string {
-  const keys = [...declared.keys()]
-  return `${keys.length}:${keys[0] ?? ''}:${keys[keys.length - 1] ?? ''}`
-}
-
-/**
- * 그 트윈의 품목 판정 함수 — 선언이 없으면 `undefined`(그때는 품목 줄을 만들지 않는다).
- *
- * 선언을 모르는 트윈에서 품목을 지어내지 않는다. 개체 줄(`lot`)은 그대로 적히므로 이력 조회는 로트로
- * 답할 수 있고, 품목 축만 비어 있다. 그 사실을 조회하는 쪽이 말한다.
- */
-export function itemResolverFor(domainId: string, instanceId: string, model: any): ItemResolver | undefined {
-  const declared = declaredItems(model)
-  if (!declared.size) return undefined
-
-  const key = `${domainId}:${instanceId}`
-  const generation = generationOf(declared)
-  let entry = memo.get(key)
-  if (!entry || entry.generation !== generation) {
-    entry = { generation, declared, seen: new Map() }
-    memo.set(key, entry)
-  }
-  const state = entry
-
-  return (epc: string) => {
-    const hit = state.seen.get(epc)
-    if (hit !== undefined) return hit
-    /* 판정은 선언이 한다 — 후보가 둘 이상이면 `undefined` 를 내고, 그것을 「모른다」로 기억한다. */
-    const found = resolveByDeclaration(itemRefOf(epc), state.declared) ?? null
-    if (state.seen.size >= MEMO_LIMIT) state.seen.clear()
-    state.seen.set(epc, found)
-    return found
-  }
-}
-
-/** 시험이 쓰는 초기화 — 프로세스 안의 기억이므로 시험마다 비운다. */
-export function resetItemResolverMemo(): void {
-  memo.clear()
-}