@things-factory/headless-twin 10.0.5 → 10.0.7

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

@@ -27,7 +27,7 @@ export class TwinSpaceResolver {
       const benchInst = insts.find(i => (i as any).purpose === 'bench')
       const bench = !!benchInst
       const copyOf = benchInst?.copyOf
-      out.push({ spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representationCount, bench, copyOf })
+      out.push({ spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representationCount, bench, copyOf })
     }
     return out
   }
@@ -44,10 +44,10 @@ export class TwinSpaceResolver {
       const areas = await getRepository(TwinSpaceArea).find({ where: { domain: { id: domainId }, representation: { id: rep.id } }, order: { createdAt: 'ASC' } })
       representations.push({ id: rep.id, type: rep.type, name: rep.name, seq: rep.seq, isPrimary: rep.isPrimary, config: rep.config, areas: areas.map(a => ({ id: a.id, name: a.name, type: a.type, geometry: a.geometry, drillTo: a.drillTo, binding: a.binding, style: a.style })) })
     }
-    return { spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representations }
+    return { spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representations }
   }
 
-  @Mutation(returns => Boolean, { description: 'Create or update a Space (name/description/geo/primaryRepresentationId).' })
+  @Mutation(returns => Boolean, { description: 'Create or update a Space (name/description/geo/timezone/primaryRepresentationId).' })
   async saveTwinSpace(
     @Arg('spaceId') spaceId: string,
     @Arg('patch', type => ScalarObject) patch: any,

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

@@ -42,6 +42,20 @@ export class TwinSpace {
   @Field(type => ScalarObject, { nullable: true, description: 'Site georeference { lat, lon, rotation, unit } — aligns representations.' })
   geo?: any
 
+  /**
+   * 이 현장의 시각 기준 — 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
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'Id of the primary representation shown on the home/monitor.' })
   primaryRepresentationId?: string

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

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

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

@@ -0,0 +1,93 @@
+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'
+
+/*
+ * TwinStructure — **한 트윈이 거쳐 온 공장 구조들.** 리비전 하나가 그 시절의 공장이다.
+ *
+ * ── 왜 필요한가: 역사를 잃거나 거짓말을 하거나 ──────────────────────────────
+ * 공장은 바뀐다. 도장 부스를 넷 더 놓고, 라인을 하나 접는다. 그런데 지금까지는 구조 서명이 바뀌면
+ * **그 트윈의 저널을 통째로 지우는 것**이 유일한 길이었다. 안 지우면 옛 이벤트를 새 공장에 대고
+ * 접게 되어 이력이 거짓말을 하기 때문이다 — 부스가 둘이던 시절의 사실을 여섯 개짜리 공장에 접으면
+ * 그때 없던 부스에서 일이 있었던 것처럼 보인다.
+ *
+ * 그래서 선택지가 둘뿐이었다: **역사를 잃거나, 거짓말을 하거나.**
+ *
+ * 셋째 길이 이 표다. 이벤트가 `structureRev` 로 자기 구조를 달고 다니고, 재생은 구조가 바뀌는
+ * 지점에서 갈아탄 뒤 이어 접는다(`replaySegments`). 이력은 "그때 그 공장의 사실" 로 계속 읽힌다.
+ *
+ * ── 왜 board 를 통째로 담나 ─────────────────────────────────────────────────
+ * 재생하려면 **그때의 토폴로지 전체**가 필요하다. 차이(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
+
+  @Column({ type: 'simple-json' })
+  @Field(type => ScalarObject, { description: 'The full BoardDef 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.' })
+  board: 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-target/index.ts

@@ -0,0 +1,5 @@
+import { TwinTarget } from './twin-target.js'
+import { TwinTargetResolver } from './twin-target-resolver.js'
+
+export const entities = [TwinTarget]
+export const resolvers = [TwinTargetResolver]

package/server/service/twin-target/twin-target-resolver.ts

@@ -0,0 +1,124 @@
+import { Arg, Ctx, Directive, Float, Mutation, Query, Resolver } from 'type-graphql'
+
+import { getRepository } from '@things-factory/shell'
+
+import { TwinTarget } from './twin-target.js'
+import { TWIN_METRIC, isTwinMetric } from '../../engine/kpi-target.js'
+
+/*
+ * 운영 목표 조회·편집 — **현장 관리자가 트윈 화면에서** 고친다(사용자 결정 2026-08-02).
+ *
+ * 경영 KPI 관리메뉴가 아니라 여기인 이유: 목표가 숫자 옆에 있어야 맥락이 살고, 운영 임계는 자주
+ * 조정된다. 조직 단위 기간 평가는 `@things-factory/kpi` 의 일이고 이쪽으로 베껴 오지 않는다.
+ */
+@Resolver()
+export class TwinTargetResolver {
+  @Directive('@privilege(category: "twin", privilege: "query")')
+  @Query(returns => [String], {
+    description:
+      'The metric ids a twin target may refer to. Fixed in one place so a target and the fact it judges can never drift into two names.'
+  })
+  async twinTargetMetrics(): Promise<string[]> {
+    return Object.keys(TWIN_METRIC)
+  }
+
+  @Directive('@privilege(category: "twin", privilege: "query")')
+  @Query(returns => [TwinTarget], {
+    description:
+      'Operational targets in scope — site-wide targets for the space plus targets bound to the given instance. Callers judge with the narrower one when both exist.'
+  })
+  async twinTargets(
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    @Arg('instanceId', { nullable: true }) instanceId?: string
+  ): Promise<TwinTarget[]> {
+    const domainId = context.state.domain.id
+    const rows = await getRepository(TwinTarget).find({ where: { domain: { id: domainId } } })
+    return rows.filter(r => (spaceId && r.spaceId === spaceId) || (instanceId && r.instanceId === instanceId))
+  }
+
+  @Directive('@privilege(category: "twin", privilege: "mutation")')
+  @Mutation(returns => Boolean, {
+    description:
+      'Create or update one operational target. The metric must be one of twinTargetMetrics — an unknown name is rejected rather than stored, because a target nobody can evaluate reads as "no target" and hides the gap.'
+  })
+  async saveTwinTarget(
+    @Arg('metric') metric: string,
+    @Arg('target', type => Float) target: number,
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    @Arg('instanceId', { nullable: true }) instanceId?: string,
+    @Arg('axis', { nullable: true }) axis?: string,
+    @Arg('axisKey', { nullable: true }) axisKey?: string
+  ): Promise<boolean> {
+    if (!isTwinMetric(metric)) throw new Error(`unknown twin metric "${metric}" — see twinTargetMetrics`)
+    if (!Number.isFinite(target)) throw new Error('target must be a finite number')
+    if (!spaceId && !instanceId) throw new Error('a target must be scoped to a space or an instance')
+    /* 축만 있고 값이 없으면 **어디에 거는 목표인지 알 수 없다** — 조용히 전체 목표로 만들지 않는다
+       (그러면 사용자는 구역 목표를 걸었다고 믿는데 전체가 바뀐다). */
+    if (axis && !axisKey) throw new Error('axisKey is required when axis is given')
+    if (!axis && axisKey) throw new Error('axis is required when axisKey is given')
+    const domainId = context.state.domain.id
+    const repo = getRepository(TwinTarget)
+    const existing = await repo.findOne({
+      where: { domain: { id: domainId }, spaceId: spaceId ?? null, instanceId: instanceId ?? null, metric, axis: axis ?? null, axisKey: axisKey ?? null } as any
+    })
+    await repo.save(
+      repo.create({
+        ...(existing ?? {}),
+        domain: { id: domainId } as any,
+        spaceId: spaceId ?? null as any,
+        instanceId: instanceId ?? null as any,
+        axis: axis ?? null as any,
+        axisKey: axisKey ?? null as any,
+        metric,
+        target,
+        ...(existing ? { updater: context.state.user } : { creator: context.state.user, updater: context.state.user })
+      })
+    )
+    return true
+  }
+
+  @Directive('@privilege(category: "twin", privilege: "mutation")')
+  @Mutation(returns => Boolean, { description: 'Remove an operational target. Removing a target removes the judgement, not the fact — the metric keeps being reported without a verdict.' })
+  async deleteTwinTarget(
+    @Arg('metric') metric: string,
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    @Arg('instanceId', { nullable: true }) instanceId?: string,
+    @Arg('axis', { nullable: true }) axis?: string,
+    @Arg('axisKey', { nullable: true }) axisKey?: string
+  ): Promise<boolean> {
+    const domainId = context.state.domain.id
+    const repo = getRepository(TwinTarget)
+
+    /*
+     * **찾아서 그 행만 지운다.** 예전에는 조건 객체를 `delete()` 에 그대로 넘겼는데 **아무 행도
+     * 안 지워지면서 `true` 를 돌려줬다.** 사용자는 목표를 지웠다고 믿고 화면을 떠나는데 판정은 그대로
+     * 남는다(실화면에서 그렇게 당했다).
+     *
+     * 무엇이 조건을 깨뜨렸는지는 단정하지 않는다 — 이 조건에는 `domain` 관계 객체와 `null` 값들이
+     * 함께 들어 있었고(`instanceId`·`axis`·`axisKey`), 둘 다 `delete()` 의 조건 해석에서 흔한 함정이다.
+     * 같은 관계-객체 패턴을 쓰는 `resetJournal` 은 실제로 잘 지우므로 관계 객체 하나만으로 설명되지
+     * 않는다. `null` 조건이 `IS NULL` 이 아니라 `= NULL` 로 나갔을 가능성이 크다.
+     *
+     * 그래서 조건을 고쳐 맞추는 대신 **행을 찾아 id 로 지운다**: 저장 경로와 **같은 조회 규칙**을
+     * 쓰므로 규칙이 갈라지지 않고(`findOne` 은 `null` 을 제대로 다룬다), 지우는 대상이 정확히 한
+     * 행이라 넓게 지울 위험도 없다.
+     */
+    const row = await repo.findOne({
+      where: {
+        domain: { id: domainId },
+        spaceId: spaceId ?? null,
+        instanceId: instanceId ?? null,
+        axis: axis ?? null,
+        axisKey: axisKey ?? null,
+        metric
+      } as any
+    })
+    /* 지울 것이 없으면 **없었다고 답한다.** 지우지 않고 true 를 주면 위와 같은 거짓말이 된다. */
+    if (!row) return false
+    await repo.delete(row.id)
+    return true
+  }
+}

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

@@ -0,0 +1,97 @@
+import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
+import { ObjectType, Field, ID, Float } from 'type-graphql'
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+
+/*
+ * TwinTarget — **운영 목표.** "이 구간의 처리량이 목표에 닿았나" 를 판단하는 기준선.
+ *
+ * ── 왜 트윈이 갖나 (사용자 결정 2026-08-02) ─────────────────────────────────
+ * `@things-factory/kpi` 와 **경계를 나눈다**:
+ *   트윈(여기)      이 구간·이 교대·이 공간의 **즉시 판단**. 현장 관리자가 트윈 화면에서 고친다.
+ *                   값은 저널 폴드에서 그때그때 계산된다(저장된 값을 읽지 않는다).
+ *   packages/kpi    **기간 평가**(조직·분기·점수·가중치·알림). 값이 저장돼 있어야 도는 체계다.
+ *
+ * 지키는 규칙 하나: **트윈은 경영 목표를 복제하지 않는다.** 조직 단위 평가가 필요하면 트윈의 사실을
+ * 내보내 그쪽이 소비하고, 그쪽 목표를 여기로 베껴 오지 않는다 — 베끼는 순간 두 개의 진실이 된다.
+ *
+ * ── 범위 (scope) ───────────────────────────────────────────────────────────
+ * `spaceId` 로 현장 전체에, `instanceId` 로 트윈 하나에 건다. 둘 다 있으면 **인스턴스가 이긴다**
+ * (좁은 선언이 넓은 선언을 덮는다 — 예외를 표현할 수 있어야 한다).
+ *
+ * 관점 축별 목표(구역마다 다른 목표)는 **아직 아니다** — 축 교차는 목표가 화면에서 쓰이기 시작한 뒤의
+ * 일이고, 처음부터 넣으면 쓰이지 않는 구조가 먼저 굳는다(performance.md §5.4-5).
+ *
+ * (CLAUDE.md: 모든 @ObjectType/@Field 영문 description 필수.)
+ */
+@Entity()
+@Index('ix_twin_target_0', (e: TwinTarget) => [e.domain, e.spaceId, e.instanceId, e.metric, e.axis, e.axisKey], { unique: true })
+@ObjectType({
+  description:
+    'An operational performance target for a twin metric — the line that turns a measured number into a judgement. Scoped to a space or to a single instance (instance wins over space, so an exception can be expressed). Distinct from @things-factory/kpi targets, which evaluate organizations over periods; twin targets are for immediate, on-site judgement and are never copied from the management KPI system.'
+})
+export class TwinTarget {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the target record.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinTarget) => e.domain)
+  domainId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Space this target applies to (site-wide). Empty when the target is bound to a single instance.' })
+  spaceId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Instance this target applies to. When both space and instance match, the instance target wins so an exception can be expressed.' })
+  instanceId?: string
+
+  /**
+   * 관점 축과 그 값 — **"이 구역만", "이 교대만" 목표가 다르다.**
+   *
+   * 둘 다 비어 있으면 **전체 목표**다(창 전체의 집계를 판정한다). 축 목표는 전체 목표를 덮지 않는다 —
+   * 다른 질문이기 때문이다: "현장 전체가 100건" 과 "용접 구역이 30건" 은 동시에 참일 수 있다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Perspective axis this target applies to (area, shift, resource, taskKind, location, order). Empty means the target judges the window total. An axis target does not override the total — "the site does 100" and "the weld area does 30" are both true at once.' })
+  axis?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The value on that axis (an area id, a shift name…). Required when axis is set.' })
+  axisKey?: string
+
+  @Column()
+  @Field({ description: 'Metric id from the twin metric vocabulary (throughput.tasks, workTime.p50Ms, …). Names are fixed in one place so target and fact never drift into two dialects.' })
+  metric: string
+
+  @Column({ type: 'float' })
+  @Field(type => Float, { description: 'The target value, in the metric\'s own unit (count, milliseconds, ratio). Whether higher or lower is better is a property of the metric, not of this record — so a target can never be declared in the wrong direction.' })
+  target: number
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who created this target.' })
+  creator?: User
+
+  @RelationId((e: TwinTarget) => e.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who last updated this target.' })
+  updater?: User
+
+  @RelationId((e: TwinTarget) => e.updater)
+  updaterId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when the target was created.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when the target was last updated.' })
+  updatedAt?: Date
+}

package/test/capability-mapping.test.ts

@@ -63,14 +63,14 @@ test('능력 소싱 구조: 4 자원/위치 능력은 카탈로그 타입에서,
 
 test('★ 스트림라인 브릿지: 능력의 상태필드가 라이브 payload 에 실림 (커널→보드 도달)', () => {
   // storable 노드 → occupancy/capacity (+ operable status)
-  const nodeD: any = buildEntityDeltas({ nodes: [{ id: 'n', type: 'storage', occupancy: 2, capacity: 9, status: 'idle' }] })[0].data
+  const nodeD: any = buildEntityDeltas({ locations: [{ id: 'n', type: 'storage', occupancy: 2, capacity: 9, status: 'idle' }] })[0].data
   for (const f of stateFieldsOf(['storable'])) assert.ok(f in nodeD, `storable payload.${f}`)
   assert.ok('status' in nodeD, 'operable(노드 status) payload')
 
   // mobile+operable 무버 → location/motion/status
-  const moverD: any = buildEntityDeltas({ movers: [{ id: 'm', kind: 'forklift', location: 'n', status: 'busy', motion: { toNode: 'n2', progress: 0.3 } }] }).find(x => x.tag === 'm')!.data
-  for (const f of stateFieldsOf(['mobile'])) assert.ok(f in moverD, `mobile payload.${f}`)
-  for (const f of stateFieldsOf(['operable'])) assert.ok(f in moverD, `operable payload.${f}`)
+  const equipmentD: any = buildEntityDeltas({ equipment: [{ id: 'm', kind: 'forklift', location: 'n', status: 'busy', motion: { toNode: 'n2', progress: 0.3 } }] }).find(x => x.tag === 'm')!.data
+  for (const f of stateFieldsOf(['mobile'])) assert.ok(f in equipmentD, `mobile payload.${f}`)
+  for (const f of stateFieldsOf(['operable'])) assert.ok(f in equipmentD, `operable payload.${f}`)
 
   // trackable 오더 → progress/held (lifecycle 은 payload 에서 'status' 로 표면화 — 이름-매핑 시임)
   const orderD: any = buildEntityDeltas({ orders: [{ id: 'o', status: 'picking', progress: 0.5, held: false }] }).find(x => x.tag === 'o')!.data
@@ -81,7 +81,7 @@ test('★ 스트림라인 브릿지: 능력의 상태필드가 라이브 payload
 test('시임 문서화 · processable output(양품/불량)은 payload oee.good/scrap 으로 표면화', () => {
   // 계약 stateField = 'output' 이나, 라이브 payload 는 이를 oee(정수%+good/scrap)로 집약해 표면화.
   const d: any = buildEntityDeltas({
-    movers: [{ id: 'c', kind: 'cutter', status: 'busy', oee: { overall: 0.8, availability: 0.9, performance: 0.9, quality: 0.98, goodCount: 10, scrapCount: 1 } }]
+    equipment: [{ id: 'c', kind: 'cutter', status: 'busy', oee: { overall: 0.8, availability: 0.9, performance: 0.9, quality: 0.98, goodCount: 10, scrapCount: 1 } }]
   }).find(x => x.tag === 'c')!.data
   assert.ok(d.oee, 'processable → payload.oee 존재')
   assert.equal(d.oee.good, 10, 'output.good = oee.good')

package/test/duration-estimators.test.ts

@@ -0,0 +1,144 @@
+/*
+ * 소요시간 추정기 — **상수를 데이터로 바꾸는 두 층(실측 · 거리×속도).**
+ *
+ * 커널 `durationOf` 의 우선순위는 추정기 > 명세 > 상수다. 그 추정기 자리에 호스트가 넣는 두 가지를
+ * 여기서 고정한다. 핵심 규율은 하나다 — **모르면 답하지 않는다**(undefined → 커널이 명세·상수로).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { EQUIPMENT_PROPERTY, buildTravelEstimator, chainEstimators } from '../server/engine/travel-estimator.ts'
+import { DEFAULT_MIN_SAMPLES, buildMeasuredEstimator } from '../server/engine/measured-estimator.ts'
+
+const layout = { dock: { x: 0, y: 0 }, rack: { x: 30, y: 40 } } // 거리 50m
+const equipment = (uom?: string, value = '2') => [
+  { id: 'fk-1', kind: 'forklift', properties: [{ id: EQUIPMENT_PROPERTY.speed, value, ...(uom ? { uom } : {}) }] }
+]
+
+/* ── 거리 × 속도 ────────────────────────────────────────────────────────── */
+
+test('거리와 속도가 있으면 이동시간을 계산한다 — 상수 30초가 아니라 50m/2(m/s)=25초', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'm' })
+  assert.deepEqual(reasons, [])
+  assert.equal(estimator!.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'rack', resourceKind: 'forklift' }), 25_000)
+})
+
+test('단위 코드를 표준대로 환산한다 — KMH 는 m/s 가 아니다', () => {
+  const { estimator } = buildTravelEstimator({ layout, equipment: equipment('KMH', '7.2'), unit: 'm' })
+  // 7.2 km/h = 2 m/s → 50m = 25초
+  assert.equal(estimator!.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'rack', resourceKind: 'forklift' }), 25_000)
+})
+
+test('단위 없는 속도는 m/s 라고 가정하지 않는다 — 3 이 초속 3m 인지 시속 3km 인지 뜻이 다르다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: equipment(undefined), unit: 'm' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('unit of measure')))
+})
+
+test('모르는 단위 코드는 받지 않는다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: equipment('WAT'), unit: 'm' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('unknown speed unit')))
+})
+
+test('좌표가 없으면 만들지 않고 이유를 남긴다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout: {}, equipment: equipment('MTS'), unit: 'm' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('no location coordinates')))
+})
+
+test('속도를 아무도 선언하지 않으면 거리만으로 시간을 만들지 않는다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: [{ id: 'fk-1', kind: 'forklift' }], unit: 'm' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('speed')))
+})
+
+test('좌표 단위가 미터가 아니면 환산을 추측하지 않는다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'ft' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('not metres')))
+})
+
+test('같은 자리의 작업(처리·체류)은 다루지 않는다 — 거리 0 을 0 초로 만들면 공정 시간이 사라진다', () => {
+  const { estimator } = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'm' })
+  assert.equal(estimator!.estimate({ kind: 'cut', fromNode: 'rack', toNode: 'rack', resourceKind: 'forklift' }), undefined)
+})
+
+test('좌표 모르는 노드·속도 모르는 자원종류는 넘긴다(부분 적용)', () => {
+  const { estimator } = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'm' })
+  assert.equal(estimator!.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'rack-99', resourceKind: 'forklift' }), undefined)
+  assert.equal(estimator!.estimate({ kind: 'spot', fromNode: 'dock', toNode: 'rack', resourceKind: 'hostler' }), undefined)
+  assert.equal(estimator!.estimate({ kind: 'spot', fromNode: 'dock', toNode: 'rack' }), undefined, '자원 종류 미지')
+})
+
+/* ── 실측(이력) ─────────────────────────────────────────────────────────── */
+
+test('작업 종류별 작업시간 p50 을 소요로 배운다 — 리드타임(대기 포함)이 아니라 작업시간', () => {
+  const r = buildMeasuredEstimator([
+    { key: 'putaway', workTime: { count: 40, p50Ms: 47_000 } },
+    { key: 'pick', workTime: { count: 12, p50Ms: 22_500 } }
+  ])
+  assert.deepEqual(r.learned, { putaway: 47_000, pick: 22_500 })
+  assert.deepEqual(r.estimator!.estimate({ kind: 'putaway', fromNode: 'a', toNode: 'b' }), { meanMs: 47_000 })
+  assert.equal(r.estimator!.estimate({ kind: 'unseen', fromNode: 'a', toNode: 'b' }), undefined, '못 배운 종류는 넘긴다')
+})
+
+/* ── 관측된 퍼짐 ────────────────────────────────────────────────────────── */
+
+test('두 꼬리가 있으면 퍼짐까지 배운다 — 평균만 배우면 줄이 생기지 않는다', () => {
+  const r = buildMeasuredEstimator([{ key: 'putaway', workTime: { count: 40, p10Ms: 30_000, p50Ms: 47_000, p90Ms: 80_000 } }])
+  assert.deepEqual(r.spreads, { putaway: { minMs: 30_000, maxMs: 80_000 } })
+  assert.deepEqual(r.estimator!.estimate({ kind: 'putaway', fromNode: 'a', toNode: 'b' }), {
+    meanMs: 47_000,
+    spread: { distribution: 'triangular', minMs: 30_000, maxMs: 80_000, modeMs: 47_000 }
+  })
+})
+
+test('한쪽 꼬리만 있으면 퍼짐을 만들지 않는다 — 아래쪽을 위쪽에서 베끼는 것은 발명이다', () => {
+  const r = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 40, p50Ms: 20_000, p90Ms: 40_000 } }])
+  assert.deepEqual(r.spreads, {})
+  assert.deepEqual(r.estimator!.estimate({ kind: 'pick', fromNode: 'a', toNode: 'b' }), { meanMs: 20_000 })
+})
+
+test('구간이 성립하지 않으면 퍼짐 없이 평균만 — 없는 흔들림을 만들지 않는다', () => {
+  const r = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 40, p10Ms: 50_000, p50Ms: 20_000, p90Ms: 20_000 } }])
+  assert.deepEqual(r.spreads, {}, 'p10 >= p90 이면 구간이 아니다')
+})
+
+test('표본이 적으면 배우지 않고, 무엇을 버렸는지 밝힌다 — 두 건의 p50 은 현장 값이 아니다', () => {
+  const r = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 2, p50Ms: 9_000 } }])
+  assert.equal(r.estimator, undefined)
+  assert.deepEqual(r.skipped, [{ kind: 'pick', count: 2 }])
+  assert.equal(r.minSamples, DEFAULT_MIN_SAMPLES)
+})
+
+test("'unknown' 축은 배우지 않는다 — 종류 모르는 기록을 특정 종류의 근거로 쓰지 않는다", () => {
+  const r = buildMeasuredEstimator([{ key: 'unknown', workTime: { count: 99, p50Ms: 30_000 } }])
+  assert.deepEqual(r.learned, {})
+  assert.equal(r.estimator, undefined)
+})
+
+test('p50 이 0 이면 쓰지 않는다 — 0 초 작업은 측정 실패다', () => {
+  const r = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 50, p50Ms: 0 } }])
+  assert.deepEqual(r.learned, {})
+})
+
+test('그룹이 없으면 빈 결과 — 던지지 않는다', () => {
+  assert.equal(buildMeasuredEstimator(undefined).estimator, undefined)
+  assert.equal(buildMeasuredEstimator([]).estimator, undefined)
+})
+
+/* ── 사슬 — 실측이 계산을 이긴다 ────────────────────────────────────────── */
+
+test('실측이 먼저, 없으면 거리 계산 — 강한 근거가 앞이다', () => {
+  const measured = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 30, p50Ms: 11_000 } }])
+  const travel = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'm' })
+  const chained = chainEstimators([measured.estimator, travel.estimator])!
+  assert.deepEqual(chained.estimate({ kind: 'pick', fromNode: 'dock', toNode: 'rack', resourceKind: 'forklift' }), { meanMs: 11_000 }, '실측 우선')
+  assert.equal(chained.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'rack', resourceKind: 'forklift' }), 25_000, '실측 없으면 거리')
+  assert.equal(chained.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'dock', resourceKind: 'forklift' }), undefined, '둘 다 모르면 넘긴다')
+})
+
+test('빈 사슬은 undefined — 주입하지 않는다(상수로 굴러가는 것이 정직하다)', () => {
+  assert.equal(chainEstimators([undefined, undefined]), undefined)
+})