@things-factory/headless-twin 10.0.17 → 10.0.19

package/server/service/twin-backfill/backfill-shape.ts

@@ -0,0 +1,86 @@
+/*
+ * 지난 기록 채우기의 **판단** — 저장소를 모르는 순수 함수.
+ *
+ * 무엇을 받고 무엇을 거절하는지가 이 파일에 다 있다. 저장소를 아는 코드(`backfill-period-facts`)는
+ * 이 판단을 부르고 쓰기만 한다. 갈라 두는 이유는 이 저장소가 이미 쓰는 방식이다 —
+ * 판단은 시험이 데이터베이스 없이 지킬 수 있어야 한다(§`event-type-split-shape`).
+ */
+
+/** 이 길이 받는 사실 — 마감된 구간을 말하는 것들. */
+export const PERIOD_FACTS: readonly string[] = [
+  'energy.usage.period',
+  'energy.generation.period',
+  'energy.generation.price',
+  'energy.tariff.basis',
+  'energy.bill'
+]
+
+export interface BackfillJudgement {
+  /** 저널에 넣어도 되는 것. */
+  keep: any[]
+  /** 받지 않은 것과 그 이유 — 조용히 버리지 않는다. */
+  refused: { record: unknown; reason: string }[]
+}
+
+/**
+ * 무엇을 채울 수 있나.
+ *
+ * 세 가지로 거절한다.
+ *
+ *   마감된 구간이 아니다   상태를 바꾸는 사실을 저널에만 넣으면 상태와 저널이 갈라진다
+ *   아직 오지 않은 시각    지난 기록이 아니다
+ *   보존보다 오래됐다      넣어도 다음 정리에서 지워진다 — 조용히 사라지느니 거절한다
+ */
+export function judgeBackfill(
+  envelopes: readonly any[],
+  opts: { nowMs: number; retentionDays?: number }
+): BackfillJudgement {
+  const keep: any[] = []
+  const refused: { record: unknown; reason: string }[] = []
+  const horizonMs = opts.retentionDays === undefined ? undefined : opts.nowMs - opts.retentionDays * 86_400_000
+
+  for (const env of envelopes) {
+    const type = String(env?.eventType ?? '')
+    if (!PERIOD_FACTS.includes(type)) {
+      refused.push({
+        record: env,
+        reason:
+          `${type} 는 마감된 구간 사실이 아니다 — 이 길은 저널에만 쓰므로, 상태를 바꾸는 사실을 여기로 넣으면 ` +
+          '상태와 저널이 갈라진다. 라이브 문으로 보내라'
+      })
+      continue
+    }
+    const atMs = Date.parse(String(env?.eventTime ?? ''))
+    if (!Number.isFinite(atMs)) {
+      refused.push({ record: env, reason: '사건 시각을 읽을 수 없다' })
+      continue
+    }
+    if (atMs > opts.nowMs) {
+      refused.push({ record: env, reason: `아직 오지 않은 시각이다(${env?.eventTime}) — 지난 기록이 아니다` })
+      continue
+    }
+    if (horizonMs !== undefined && atMs < horizonMs) {
+      refused.push({
+        record: env,
+        reason:
+          `보존 기간(${opts.retentionDays}일)보다 오래됐다(${env?.eventTime}) — 넣어도 다음 정리에서 지워진다. ` +
+          '더 뒤까지 보려면 보존 기간을 늘려야 한다'
+      })
+      continue
+    }
+    keep.push(env)
+  }
+
+  return { keep, refused }
+}
+
+/**
+ * 이미 있는 것을 가려낸다 — **정체성은 내용에 있다**(커널 0.7.81).
+ *
+ * 저장소의 제약으로 막지 않는 이유는 드라이버가 다섯이고 충돌 처리가 제각각이기 때문이다.
+ * 구간 단위로 한 번 읽어 가려내는 편이 이식성이 있고 값도 싸다.
+ */
+export function splitAlreadyThere(keep: readonly any[], existingIds: ReadonlySet<string>): { fresh: any[]; skipped: number } {
+  const fresh = keep.filter(e => typeof e?.eventId === 'string' && e.eventId && !existingIds.has(e.eventId))
+  return { fresh, skipped: keep.length - fresh.length }
+}

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

@@ -0,0 +1,3 @@
+import { TwinBackfillResolver } from './twin-backfill-resolver.js'
+
+export const resolvers = [TwinBackfillResolver]

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

@@ -0,0 +1,35 @@
+import { Arg, Ctx, Directive, Mutation, Resolver } from 'type-graphql'
+import { ScalarObject } from '@things-factory/shell'
+
+import { backfillPeriodFacts } from './backfill-period-facts.js'
+
+/*
+ * 지난 기록 채우기의 **문** — 커넥터가 트윈이 없던 동안의 날들을 뒤늦게 넣는다.
+ *
+ * ── 왜 문을 따로 두나 (2026-08-30) ────────────────────────────────────────
+ * 라이브 유입과 판단이 다르다. 라이브는 트윈의 「지금」을 바꾸고, 이쪽은 저널에만 쓴다. 같은 문으로
+ * 받으면 옛 표본이 가드에 막히거나 트윈의 시계가 과거로 끌린다(§`backfill-period-facts`).
+ *
+ * 레코드의 **모양은 라이브와 같다** — 커넥터가 다른 어휘를 배울 필요가 없다. 다른 것은 받는 종류뿐이고,
+ * 그 판단은 커널의 유입과 `judgeBackfill` 이 한다.
+ *
+ * ── 왜 이 파일이 늦게 생겼나 ──────────────────────────────────────────────
+ * 채우기 자체는 만들어 두고 **부르는 곳을 만들지 않아** 쓸 수 없는 채로 있었다. 8월 29일 발전량을
+ * 되살리려다 드러났다. 같은 부류를 그날 두 번 겪었다(커널의 발전 기간 문도 없었다).
+ */
+@Resolver()
+export class TwinBackfillResolver {
+  /* 트윈의 모든 변경과 같은 게이트다(ADR-0027) — 저널에 사실을 적는 일이므로 변경이다. */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Backfill closed-period facts into a twin journal without touching its live state. Records use the same shape as live ingest; only closed-period facts are accepted (usage/generation periods, generation price, tariff basis, bill). Point-in-time observations are refused with a reason, as are times beyond journal retention. Re-running is safe: a period already present is skipped, because a closed period is identified by its content. Returns { written, skipped, refused }.'
+  })
+  async backfillTwinPeriodFacts(
+    @Arg('instanceId') instanceId: string,
+    @Arg('records', type => [ScalarObject]) records: unknown[],
+    @Ctx() context: ResolverContext
+  ): Promise<{ written: number; skipped: number; refused: { record: unknown; reason: string }[] }> {
+    return await backfillPeriodFacts({ domainId: context.state.domain.id, instanceId, records })
+  }
+}

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

@@ -1,7 +1,7 @@
 import { twinError } from '../../engine/log.js'
 import { Arg, Ctx, Mutation, Query, Resolver, Directive } from 'type-graphql'
 
-import { validateScenario } from '@operato/twin-kernel'
+import { validateScenario } from '@operato/ops-contract'
 
 import { ScalarObject } from '@things-factory/shell'
 

package/server/service/twin-lifecycle/domain-catalog.ts

@@ -6,7 +6,8 @@
  * 조합을 재현하면 프로파일 병합(mes.products)이나 능력 메타 포함 여부가 갈린다(방언).
  */
 /* 커널은 CJS 배포 — ESM import 대신 require(리졸버의 기존 관행과 동일). */
-const { DOMAIN_CATALOG, MES_PRODUCTS, CAPABILITIES, capabilitiesForType } = require('@operato/twin-kernel')
+const { MES_PRODUCTS } = require('@operato/twin-kernel')
+const { DOMAIN_CATALOG, CAPABILITIES, capabilitiesForType } = require('@operato/ops-contract')
 
 /**
  * 시스템별(wms/yms/mes) 노드·설비 타입과 각 타입의 능력을 담은 카탈로그.

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

@@ -7,7 +7,7 @@ import { TwinEngine } from '../../engine/index.js'
 import { readRestartPolicy } from '../../engine/restart-policy.js'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 
-import type { TwinModelDef } from '@operato/twin-kernel'
+import type { TwinModelDef } from '@operato/ops-contract'
 
 /* 도메인 어휘 카탈로그(시스템별 노드 타입) — 커널이 SSOT. 앱/UI 는 이걸 소싱하고 재선언하지 않는다(방언 금지).
  * 조합은 domain-catalog.ts 가 소유 — 리졸버와 서버측 소비자(board-ai 도구 등)가 같은 형태를 본다. */

package/server/service/twin-model/name-index.ts

@@ -6,7 +6,7 @@
  * 두 벌을 만들면 한쪽만 고쳐지므로 한 곳에 둔다(재발명 금지).
  */
 /* 커널 런타임 로드 — 어느 축이 있는지는 카탈로그가 선언한다(이 파일은 도메인 모양을 알지 않는다). */
-const { TWIN_AXES, axisSource } = require('@operato/twin-kernel')
+const { TWIN_AXES, axisSource } = require('@operato/ops-contract')
 
 /** `productionSpec.definition.recipes` 같은 경로를 문서에서 따라간다. */
 export const at = (o: any, path: string) => path.split('.').reduce((a: any, k: string) => (a == null ? undefined : a[k]), o)

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

@@ -5,7 +5,7 @@ import { TwinArea } from '../twin-space/twin-area.js'
 import { TwinLocation } from './twin-location.js'
 import { TwinEquipment } from './twin-equipment.js'
 import { TwinOperation } from './twin-operation.js'
-import { readBoardEquipment } from '@operato/twin-kernel'
+import { readBoardEquipment } from '@operato/ops-contract'
 
 /*
  * 구조 투영 — `model`(커널 입력 문서) → **표준 엔티티 행**(ADR-0032).
@@ -149,7 +149,8 @@ export async function projectStructure(domainId: string, instanceId: string, mod
         homeLocation: home ? ({ id: home.id } as any) : null,
         mtbfMs: m.mtbfMs ?? null,
         mttrMs: m.mttrMs ?? null,
-        gs1Id: m.gs1Id ?? null,
+        /* 선언된 정체성 — 예전에는 선언에 없는 `gs1Id` 를 읽어 이 칸이 늘 비어 있었다. */
+        identity: (m as any).identity ?? null,
         sourceRef,
         ingestedAt
       } as any)

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

@@ -127,9 +127,21 @@ export class TwinEquipment {
   @Field(type => Int, { nullable: true, description: 'Declared mean time to repair in ms.' })
   mttrMs?: number
 
+  /*
+   * ── **선언된 설비 정체성** (2026-08-30) ───────────────────────────────────
+   *
+   * 예전 이름은 `gs1Id` 였고, 투영이 선언의 `m.gs1Id` 를 읽었다. **그런 필드가 선언에 없다** — 그래서
+   * 이 칸은 일곱 대 모두 영원히 비어 있었다. 자리는 있고 길이 없었다.
+   *
+   * 그 사이 커널에 `TwinModelDef.equipment[].identity` 를 열었으므로 어휘가 두 벌이 됐다. 하나로
+   * 합친다. 이름을 `identity` 로 두는 이유는 **GS1 키가 아닌 정체성이 정상**이기 때문이다 —
+   * 실측한 값은 인버터의 하드웨어 식별자(`ES100000007d8d061d-1`)이고 GS1 키가 아니다.
+   *
+   * 자리(`twin_location`)의 `gs1Id` 는 그대로 둔다. 그쪽은 실제로 SGLN 이 온다.
+   */
   @Column({ nullable: true })
-  @Field({ nullable: true, description: 'GS1 identifier supplied by the source (e.g. GIAI).' })
-  gs1Id?: string
+  @Field({ nullable: true, description: 'Declared global identity of this equipment (TwinModelDef.equipment[].identity). Not necessarily a GS1 key.' })
+  identity?: string
 
   /* ── 캐시라는 사실을 구조로 (ADR-0032-D) ── */
   @Column()

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

@@ -17,7 +17,7 @@ import { TwinArea } from '../twin-space/twin-area.js'
 import { at, idOf, nameIndex, namesFor } from './name-index.js'
 
 /* 커널 런타임 로드 — 축·관계·속성 선언의 SSOT. 이 파일은 도메인 모양을 알지 않는다. */
-const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, documentPath, relationsFrom, relationsTo, propertiesOf } = require('@operato/twin-kernel')
+const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, documentPath, relationsFrom, relationsTo, propertiesOf } = require('@operato/ops-contract')
 
 /**
  * 축 → 그 축이 이미 **행으로 옮겨졌나**, 그리고 행의 어느 컬럼이 id 인가.

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

@@ -8,7 +8,7 @@ import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
 import { modelGapOf } from '../../engine/model-gap.js'
-import { readBoardEquipment } from '@operato/twin-kernel'
+import { readBoardEquipment } from '@operato/ops-contract'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinSpace } from '../twin-space/twin-space.js'
 import { TwinReference } from '../reference/twin-reference.js'
@@ -45,7 +45,7 @@ import { unwrapState } from '../../engine/warm-start.js'
 import { axisValueOf } from '@things-factory/headless-twin/dist-shared/axis-read.js'
 
 /* 커널 런타임 로드 — CJS 번들(엔진과 같은 방식). 축·관계 선언의 SSOT 다. */
-const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, axisAppliesTo } = require('@operato/twin-kernel')
+const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, axisAppliesTo } = require('@operato/ops-contract')
 
 /**
  * 축 → 그 축이 이미 **행으로 옮겨졌나**. 옮겨진 축은 DB 가 세고, 아직인 축은 문서를 세어야 한다.

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

@@ -5,7 +5,7 @@ import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 
-const { TWIN_RELATIONS, axisInfo } = require('@operato/twin-kernel')
+const { TWIN_RELATIONS, axisInfo } = require('@operato/ops-contract')
 
 /**
  * 재귀 전개 — **자기 축으로 돌아오는 선언을 따라간다.**

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

@@ -486,7 +486,7 @@ export class TwinSpaceResolver {
       polygonRefs += polys.filter(p => (p.binding as any)?.groupId === areaId || (p.binding as any)?.areaId === areaId).length
     }
     if (children > 0 || polygonRefs > 0) {
-      throw new Error(`area "${areaId}" 는 참조가 남아 삭제할 수 없습니다 (자식 ${children}, 폴리곤 ${polygonRefs}). 참조 제거 후 삭제하세요.`)
+      throw new Error(`deleteArea: area "${areaId}" cannot be deleted due to existing references (children: ${children}, polygonRefs: ${polygonRefs}). Remove references first.`)
     }
     await getRepository(TwinArea).delete({ domain: { id: domainId } as any, space: { id: space.id } as any, areaId })
     return true

package/shared/entity-delta.ts

@@ -50,7 +50,7 @@ export const ENERGY_TAG_PREFIX = '__energy__'
 
 /** 이 트윈의 집약 채널 태그. 트윈 식별자가 없으면 만들지 않는다 — 덮어쓰기의 원인이었다. */
 export function aggregateTag(prefix: string, instanceId: string): string {
-  if (!instanceId) throw new Error('aggregateTag: instanceId required — 트윈 구분이 없는 태그는 다른 트윈의 것을 덮는다')
+  if (!instanceId) throw new Error('aggregateTag: instanceId required — tags without instanceId overwrite other twin states across tenants')
 
   return `${prefix}:${instanceId}`
 }

package/test/actuation-dispatch.test.ts

@@ -0,0 +1,196 @@
+/*
+ * **승인을 지나지 않은 조치는 현장에 나가지 못한다** — 배선.
+ *
+ * ── 왜 배선을 따로 보나 (2026-08-31) ─────────────────────────────────────
+ * 승인 판정 자체는 계약이 지킨다(`ops-contract/test/actuation-gate.test.ts`). 여기서 보는 것은
+ * **그 판정이 실제 경로에 서 있는가**다 — 어댑터가 불렸는가, 상태가 적혔는가, 다시 세운 뒤에도 승인이
+ * 남아 있는가.
+ *
+ * 이 저장소에서 가장 자주 나는 결함이 「자리는 있고 길이 없다」이고, 게이트가 그 부류로 나면 결과가
+ * 현장의 작업지시다. 그래서 마지막 시험이 **저장본만 남기고 다시 세운다.**
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { TwinCommand } from '@operato/ops-contract'
+
+import { approve, dispatch, reject, type CommandAck, type CommandStore } from '../server/service/actuation/command-dispatcher.js'
+
+const DOMAIN = 'd-1'
+const AT = '2026-08-31T02:00:00.000Z'
+const APPROVAL = { by: 'line-lead', at: AT }
+
+const irreversible = (over: Partial<TwinCommand> = {}): TwinCommand => ({
+  id: 'cmd-1',
+  instanceId: 'twin-a',
+  type: 'order.hold',
+  origin: 'ai',
+  proposedAt: AT,
+  state: 'proposed',
+  ...over
+})
+
+/** 저장본 하나 — 프로세스가 아니라 여기 산다. 그래서 다시 세워도 남는다. */
+function makeStore(initial: TwinCommand): CommandStore & { rows: Map<string, TwinCommand> } {
+  const rows = new Map<string, TwinCommand>([[initial.id, initial]])
+  return {
+    rows,
+    load: async (domainId, id) => (domainId === DOMAIN ? (rows.get(id) ?? null) : null),
+    /* 저장소를 흉내 내는 것이라 복사해 넣는다 — 같은 객체면 안 적혀도 통과한다. */
+    save: async (domainId, command) => {
+      assert.equal(domainId, DOMAIN)
+      rows.set(command.id, JSON.parse(JSON.stringify(command)))
+    }
+  }
+}
+
+const ok = (ref = 'JOB-1') => async (): Promise<CommandAck> => ({ ok: true, ref })
+
+/* ── 승인 없이는 나가지 못한다 ────────────────────────────────────────────── */
+
+test('★ 승인하지 않은 조치는 어댑터에 닿지 않는다', async () => {
+  const store = makeStore(irreversible())
+  let called = false
+
+  await assert.rejects(
+    dispatch(store, DOMAIN, 'cmd-1', async () => {
+      called = true
+      return { ok: true }
+    }),
+    /승인되지 않은/
+  )
+  assert.equal(called, false, '어댑터가 불렸다 — 게이트가 서지 않았다')
+  assert.equal(store.rows.get('cmd-1')!.state, 'proposed', '상태가 움직였다')
+})
+
+test('★ 상태만 approved 로 적고 승인 기록이 없으면 막는다 — 저장본을 손으로 고쳐도 열리지 않는다', async () => {
+  const store = makeStore(irreversible({ state: 'approved' }))
+  let called = false
+  await assert.rejects(
+    dispatch(store, DOMAIN, 'cmd-1', async () => {
+      called = true
+      return { ok: true }
+    }),
+    /승인 기록이 없는/
+  )
+  assert.equal(called, false)
+})
+
+test('★ 승인하면 나간다 — 어댑터가 돌려준 것이 남는다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', ok('JOB-77'))
+
+  assert.equal(settled.state, 'acked')
+  assert.equal(settled.dispatchRef, 'JOB-77', '되돌릴 때 무엇을 되돌릴지 말할 수 없게 된다')
+  assert.equal(store.rows.get('cmd-1')!.approval?.by, 'line-lead')
+})
+
+test('★ 넘기기 전에 「넘기는 중」을 먼저 적는다 — 그 사이에 죽으면 현장이 두 번 움직인다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+
+  let seenWhileDispatching: string | undefined
+  await dispatch(store, DOMAIN, 'cmd-1', async () => {
+    seenWhileDispatching = store.rows.get('cmd-1')!.state
+    return { ok: true, ref: 'x' }
+  })
+  assert.equal(seenWhileDispatching, 'dispatched', '어댑터를 부르는 동안 저장본이 아직 approved 였다')
+})
+
+/* ── 되돌릴 수 있는 것의 다른 문 ─────────────────────────────────────────── */
+
+test('★ 되돌릴 수 있는 조치는 사람 없이 지난다 — 시뮬과 what-if 가 이 길이다', async () => {
+  const store = makeStore(irreversible({ reversible: true }))
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', ok())
+  assert.equal(settled.state, 'acked')
+})
+
+test('★ 되돌릴 수 있다고 적지 않은 것은 그 문으로 못 간다 — 모름을 통과로 읽지 않는다', async () => {
+  const store = makeStore(irreversible({ reversible: false }))
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok()))
+})
+
+/* ── 실패와 되풀이 ────────────────────────────────────────────────────────── */
+
+test('★ 어댑터가 던지면 실패로 남고 이유가 적힌다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', async () => {
+    throw new Error('MES 가 응답하지 않는다')
+  })
+
+  assert.equal(settled.state, 'failed')
+  assert.match(String(settled.error), /응답하지 않는다/)
+})
+
+test('어댑터가 이유 없이 실패해도 빈 칸으로 두지 않는다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: false }))
+  assert.ok(String(settled.error).length > 0)
+})
+
+test('★ 실패한 것은 다시 넘길 수 있다 — 승인을 다시 받지 않는다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: false, error: '잠시 끊겼다' }))
+
+  const retried = await dispatch(store, DOMAIN, 'cmd-1', ok('JOB-9'))
+  assert.equal(retried.state, 'acked')
+  assert.equal(retried.dispatchRef, 'JOB-9')
+})
+
+test('★ 이미 답을 받은 것은 다시 나가지 않는다 — 두 번 나가면 현장이 두 번 움직인다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  await dispatch(store, DOMAIN, 'cmd-1', ok())
+
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok()), /넘길 수 없다/)
+})
+
+/* ── 거절 ─────────────────────────────────────────────────────────────────── */
+
+test('★ 거절하면 끝이다 — 되살아나지 않는다', async () => {
+  const store = makeStore(irreversible())
+  await reject(store, DOMAIN, 'cmd-1', { by: 'line-lead', at: AT, note: '지금 그 라인은 정지 중' })
+
+  assert.equal(store.rows.get('cmd-1')!.state, 'rejected')
+  await assert.rejects(approve(store, DOMAIN, 'cmd-1', APPROVAL))
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok()))
+})
+
+test('승인을 기다리는 중에도 거절할 수 있다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  await reject(store, DOMAIN, 'cmd-1', { by: 'plant-manager', at: AT })
+  assert.equal(store.rows.get('cmd-1')!.state, 'rejected')
+})
+
+/* ── 재기동 ───────────────────────────────────────────────────────────────── */
+
+test('★ 승인이 재기동을 넘어 산다 — 사람이 승인한 것이 사라지면 안 된다', async () => {
+  const first = makeStore(irreversible())
+  await approve(first, DOMAIN, 'cmd-1', APPROVAL)
+  const saved: TwinCommand = JSON.parse(JSON.stringify(first.rows.get('cmd-1')))
+
+  /* 프로세스가 새로 선 것으로 본다 — 앞의 저장소 객체는 버리고 저장본만 물려준다. */
+  const second = makeStore(saved)
+  const settled = await dispatch(second, DOMAIN, 'cmd-1', ok('JOB-3'))
+
+  assert.equal(settled.state, 'acked', '이어받지 못하면 승인이 사라져 던진다')
+  assert.equal(settled.approval?.by, 'line-lead')
+})
+
+test('★ 재기동이 게이트를 열지 않는다 — 되세운 것도 같은 문을 지난다', async () => {
+  /* JSON 에는 승인 표식이 없다. 되세울 때 표식을 그냥 붙이면 재기동이 곧 우회로가 된다. */
+  const saved: TwinCommand = JSON.parse(JSON.stringify(irreversible()))
+  const store = makeStore(saved)
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok()), /승인되지 않은/)
+})
+
+test('모르는 커맨드는 조용히 넘어가지 않는다', async () => {
+  const store = makeStore(irreversible())
+  await assert.rejects(dispatch(store, DOMAIN, 'nope', ok()), /모르는 커맨드/)
+  await assert.rejects(approve(store, DOMAIN, 'nope', APPROVAL), /모르는 커맨드/)
+})

package/test/axis-read.test.ts

@@ -51,7 +51,8 @@ test('커널 선언과 상태의 모양이 맞는다 — 선언한 경로에 정
    * 선언(`path`)과 실제 상태의 모양이 어긋나면 이 배선은 알리지 않고 빈 카드를 만든다. 그래서 **커널이 낸
    * 상태로** 확인한다 — 선언을 읽는 쪽과 값을 만드는 쪽이 같은 모양을 쓰는지 보는 것이 요점이다.
    */
-  const { EmsKernel, axisInfo, ENERGY_EVENT, DEMAND_WINDOW_MS } = await import('@operato/twin-kernel')
+  const { EmsKernel, DEMAND_WINDOW_MS } = await import('@operato/twin-kernel')
+const { axisInfo, ENERGY_EVENT } = await import('@operato/ops-contract')
   const info = axisInfo('demandWindows')!
   assert.ok(info, '커널이 그 축을 선언해야 한다')
   assert.equal(info.path, 'energy.closed')
@@ -134,7 +135,7 @@ test('축을 이름으로 읽는 자리가 없다 — 선언된 경로를 지나
 test('수요 구간은 실제로 중첩된 축이다 — 이 가드가 지키는 대상이 있다', () => {
   /* 가드가 지킬 것이 없으면 그 가드는 초록으로 거짓을 말한다. 대상이 실재하는지 함께 본다. */
   const req = createRequire(import.meta.url)
-  const { TWIN_AXES } = req('@operato/twin-kernel')
+  const { TWIN_AXES } = req('@operato/ops-contract')
   const nested = (TWIN_AXES as any[]).filter(a => a.path)
 
   assert.ok(nested.length > 0, '경로를 가진 축이 하나도 없으면 이 가드는 의미가 없다')
@@ -156,7 +157,7 @@ test('수요 구간은 실제로 중첩된 축이다 — 이 가드가 지키는
  */
 test('id 가 없는 상태 축은 무엇이 항목을 가리키는지 선언한다', () => {
   const req2 = createRequire(import.meta.url)
-  const { TWIN_AXES } = req2('@operato/twin-kernel')
+  const { TWIN_AXES } = req2('@operato/ops-contract')
   const dw = (TWIN_AXES as any[]).find(a => a.axis === 'demandWindows')
 
   assert.ok(dw, '수요 구간 축이 있어야 한다')

package/test/backfill-shape.test.ts

@@ -0,0 +1,89 @@
+/*
+ * 지난 기록 채우기의 판단 — **무엇을 받고 무엇을 거절하나.**
+ *
+ * ── 왜 저널에만 쓰나 (2026-08-30) ──────────────────────────────────────────
+ * 커널의 상태는 「지금」이다. 늦게 온 옛 표본은 가드가 막는다(그렇게 만들었다). 지난 기록을 라이브
+ * 문으로 넣으면 가드에 막히거나 트윈의 시계가 과거로 끌린다. 그래서 이 길은 저널에만 쓰고,
+ * **상태를 바꾸는 사실은 아예 받지 않는다.**
+ *
+ * ── 보존 안에서만 (사용자 결정) ────────────────────────────────────────────
+ * 보존보다 오래된 것을 채우면 다음 정리에서 지워진다. 조용히 넣고 지워지면 아무도 모르므로
+ * 거절하고 이유를 말한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { judgeBackfill, splitAlreadyThere, PERIOD_FACTS } from '../server/service/twin-backfill/backfill-shape.ts'
+
+const NOW = Date.parse('2026-08-30T00:00:00.000Z')
+const env = (eventType: string, eventTime: string, eventId = `${eventType}|${eventTime}`) => ({ eventType, eventTime, eventId })
+
+test('★ 마감된 구간 사실을 받는다', () => {
+  const r = judgeBackfill([env('energy.usage.period', '2026-08-29T00:00:00.000Z')], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 1)
+  assert.equal(r.refused.length, 0)
+})
+
+test('★ 상태를 바꾸는 사실은 받지 않는다 — 저널에만 넣으면 상태와 저널이 갈라진다', () => {
+  const r = judgeBackfill(
+    [env('energy.measured', '2026-08-29T00:00:00.000Z'), env('energy.generated', '2026-08-29T00:00:00.000Z')],
+    { nowMs: NOW, retentionDays: 7 }
+  )
+  assert.equal(r.keep.length, 0)
+  assert.equal(r.refused.length, 2)
+  assert.match(r.refused[0].reason, /라이브 문으로 보내라/)
+})
+
+test('★ 보존보다 오래된 것은 거절하고 이유를 말한다 — 넣어도 지워진다', () => {
+  const r = judgeBackfill([env('energy.usage.period', '2026-08-01T00:00:00.000Z')], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 0)
+  assert.match(r.refused[0].reason, /보존 기간\(7일\)보다 오래됐다/)
+  assert.match(r.refused[0].reason, /보존 기간을 늘려야 한다/, '무엇을 해야 하는지 함께 말한다')
+})
+
+test('보존 안쪽 경계는 받는다', () => {
+  const justInside = new Date(NOW - 7 * 86_400_000 + 1000).toISOString()
+  const r = judgeBackfill([env('energy.usage.period', justInside)], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 1)
+})
+
+test('보존 정책이 없으면 오래됨을 판정하지 않는다 — 없는 기준으로 거절하지 않는다', () => {
+  const r = judgeBackfill([env('energy.usage.period', '2020-01-01T00:00:00.000Z')], { nowMs: NOW })
+  assert.equal(r.keep.length, 1)
+})
+
+test('★ 아직 오지 않은 시각은 거절한다 — 지난 기록이 아니다', () => {
+  const r = judgeBackfill([env('energy.usage.period', '2026-09-01T00:00:00.000Z')], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 0)
+  assert.match(r.refused[0].reason, /아직 오지 않은 시각/)
+})
+
+test('시각을 읽을 수 없으면 거절한다', () => {
+  const r = judgeBackfill([env('energy.usage.period', 'n/a')], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 0)
+  assert.match(r.refused[0].reason, /읽을 수 없다/)
+})
+
+test('받는 종류 다섯이 모두 마감된 구간 사실이다', () => {
+  for (const t of PERIOD_FACTS) {
+    const r = judgeBackfill([env(t, '2026-08-29T00:00:00.000Z')], { nowMs: NOW, retentionDays: 7 })
+    assert.equal(r.keep.length, 1, `${t} 를 받아야 한다`)
+  }
+})
+
+/* ── 같은 기간을 두 번 넣지 않는다 ────────────────────────────────────────── */
+
+test('★ 이미 있는 것은 건너뛴다 — 다시 읽어도 중복이 쌓이지 않는다', () => {
+  const a = env('energy.usage.period', '2026-08-29T00:00:00.000Z')
+  const b = env('energy.usage.period', '2026-08-29T01:00:00.000Z')
+  const r = splitAlreadyThere([a, b], new Set([a.eventId]))
+  assert.equal(r.fresh.length, 1)
+  assert.equal(r.fresh[0].eventId, b.eventId)
+  assert.equal(r.skipped, 1)
+})
+
+test('id 가 없으면 넣지 않는다 — 같은 사실인지 판단할 근거가 없다', () => {
+  const r = splitAlreadyThere([{ eventType: 'energy.usage.period', eventTime: '2026-08-29T00:00:00.000Z' }], new Set())
+  assert.equal(r.fresh.length, 0)
+  assert.equal(r.skipped, 1)
+})

package/test/broadcast-cost-baseline.test.ts

@@ -22,7 +22,8 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { MesKernel, type CanonicalEnvelope, type ProductionSpec, type ScenarioDef, type TwinModelDef } from '@operato/twin-kernel'
+import { MesKernel } from '@operato/twin-kernel'
+import { type CanonicalEnvelope, type ProductionSpec, type ScenarioDef, type TwinModelDef } from '@operato/ops-contract'
 
 import { buildEntityDeltas } from '../shared/entity-delta.ts'