@things-factory/headless-twin 10.0.15 → 10.0.18

package/server/service/reference/reference-master.ts

@@ -7,7 +7,7 @@
  * 좌표·representations 는 트윈 공간층(보완/추가). 실 시스템이 좌표를 안 주면 layout 없이 위상만 인제스트.
  */
 
-import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/twin-kernel'
+import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/ops-contract'
 
 export interface RefLocation {
   id: string
@@ -118,7 +118,7 @@ export interface RefTestResult {
   specId: string
   result: 'pass' | 'fail'
   at?: string
-  /** 없으면 무기한 — 짐작으로 기한을 만들면 멀쩡한 자격자가 조용히 사라진다. */
+  /** 없으면 무기한 — 짐작으로 기한을 만들면 멀쩡한 자격자가 오류 없이 사라진다. */
   expiresAt?: string
 }
 
@@ -150,7 +150,16 @@ export interface RefEquipment {
   homeLocationId: string
   mtbfMs?: number // 평균 고장 간격(확률적 고장) — 지정 시 커널이 breakdown 시뮬 → 주목(고장) 발생
   mttrMs?: number // 평균 수리 시간
-  gs1Id?: string // 정식 GS1 정체성(§J) — 설비=GIAI.
+  /**
+   * **이 설비의 전역 정체성** — 커널 선언의 `equipment[].identity` 로 그대로 간다.
+   *
+   * 예전 이름은 `gs1Id` 였다. 그런데 **GS1 키가 아닌 것이 정상이다** — 실측한 값은 인버터의
+   * 하드웨어 식별자(`ES100000007d8d061d-1`)이고, 원본이 GIAI 를 주면 그것도 여기 들어온다.
+   * 이름이 한 종류만 가리키면 다른 종류가 들어올 때 그 자리를 못 쓴다.
+   *
+   * 자리(`RefLocation.gs1Id`)는 그대로다 — 그쪽은 실제로 SGLN 이 온다.
+   */
+  identity?: string
   /**
    * 교대(가동시간) — 이 시간대에만 배정된다. `startHour <= endHour` 면 같은 날, 넘어가면 야간(22→6).
    * 미지정=24시간 가용. 교대 밖 자원은 고장·계획정지와 **구별되는 이유**로 쉰다(상태에 드러난다).
@@ -177,7 +186,7 @@ export interface RefEquipment {
    *
    * 없으면 **폐기한 것이 영구히 살아 있다**: 배정 대상에 남고, 가용 수에 들어가고, 화면에 뜬다.
    * 도입 예정인 것은 반대로 오늘부터 있는 것처럼 보인다. 기간 밖이면 커널이 그 시각의 모델에서
-   * 빼고 **이유를 달아 남긴다**(`effectivity: 'not-yet' | 'expired'`) — 조용히 지우지 않는다.
+   * 빼고 **이유를 달아 남긴다**(`effectivity: 'not-yet' | 'expired'`) — 알리지 않고 지우지 않는다.
    */
   effectiveStart?: string
   effectiveEnd?: string
@@ -226,7 +235,7 @@ export interface RefOperationVariability {
  *
  * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 고정한 상수다.** 원 시스템(또는 가상 레퍼런스)이
  * 공정별 소요·변동·수율을 말해 줘야 예측이 그 현장의 예측이 된다. 주지 않으면 커널 기본값으로
- * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(조용히 넘어가지 않는다).
+ * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(알리지 않고 넘어가지 않는다).
  */
 export interface RefOperation {
   /** 작업 종류 키 — 커널 `FlowTask.kind` 와 같은 값이어야 명세가 그 작업에 붙는다. */
@@ -366,7 +375,7 @@ export type MasterOrigin =
   /**
    * 템플릿 + 노브로 합성했다 — 다시 읽기 = 같은 노브로 다시 짓는다(합성은 결정적이다).
    *
-   * `spaceId` 는 **만들 때 고른 현장**이다(합쳐 넣기). 기억하지 않으면 다시 읽을 때 트윈이 조용히 자기
+   * `spaceId` 는 **만들 때 고른 현장**이다(합쳐 넣기). 기억하지 않으면 다시 읽을 때 트윈이 알리지 않고 자기
    * 현장을 떠난다 — 템플릿이 낸 기본 공간으로 돌아가기 때문이다. 그러면 그 현장의 값(요금 등)도 함께
    * 잃는다(2026-08-18 실측: 한 현장에 합쳐 둔 EMS 트윈 여덟이 재동기 뒤 각자 공간으로 흩어졌다).
    */
@@ -457,7 +466,7 @@ export interface ReferenceMaster {
    * 여기에 담아 보낸다 — 그러면 `masterToTwin` 의 경고와 한 줄기로 합쳐져 화면까지 간다.
    *
    * 이 자리가 없던 동안 커넥터는 할 말이 있어도 **말할 곳이 없었다.** 그래서 도크를 랙으로 바꿔
-   * 놓고도 조용히 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
+   * 놓고도 알리지 않고 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
    */
   warnings?: IngestWarning[]
   /**
@@ -498,7 +507,7 @@ export interface IngestedTwin {
  * 호스트가 절대 구간(`StartDateTime`/`FinishDateTime`)을 계산해 넣는 것이고, 그때 이 함수는 사라진다.
  *
  * 모르는 이름에는 **0 을 답하지 않는다**(`undefined`) — 0 은 "UTC 라고 선언했다" 는 뜻이고, 모르는 것을
- * 그렇게 바꾸면 판정이 조용히 틀린다.
+ * 그렇게 바꾸면 판정이 오류 없이 틀린 값을 낸다.
  */
 export function utcOffsetOf(timezone?: string, at: Date = new Date()): number | undefined {
   if (!timezone) return undefined
@@ -553,7 +562,7 @@ export interface IngestWarning {
  * 형상은 **시각별 비율**이라, 시간대가 없으면 현장 정오가 아니라 UTC 정오에 피크가 선다(KST 현장이면
  * 밤 9시). 값이 그럴듯하게 나오므로 아무도 알아채지 못한다.
  *
- * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 조용히
+ * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 알리지 않고
  * 그 가정 위에 선다) 대신 **그 조합을 말한다** — 공간에 시간대를 선언하면 사라지는 경고다.
  */
 export const generationWithoutTimeZone = (spaceId: string, equipmentId: string): IngestWarning => ({
@@ -576,9 +585,20 @@ export const generationWithoutTimeZone = (spaceId: string, equipmentId: string):
 export const unknownLocationType = (system: string, type: string, id: string): IngestWarning => ({
   code: 'unknown-location-type',
   params: { system, type, id },
+  /*
+   * ── 무슨 일이 벌어지는지 말한다 (2026-08-25) ────────────────────────────────
+   * 예전 문장은 「흐름에 참여하지 못할 수 있다」였다. 물건이 흐르는 도메인에서는 맞는 말인데,
+   * 에너지 트윈에는 흐름이 없어서 그 문장이 아무것도 알려 주지 않았다(실제로 태양광 발전소를
+   * 붙이면서 이 경고를 받은 사람이 「이 경고가 뜻이 있는가」를 되물었다).
+   *
+   * 종류를 모르면 실제로 일어나는 일은 하나다: **그 자리에 능력이 붙지 않는다.** 능력이 없으면
+   * 상태 필드도 없고, 롤업에도 들어가지 않고, 저작면 팔레트에도 서지 않는다. 도메인을 가리지 않고
+   * 참인 문장이므로 이것을 적는다.
+   */
   message:
     `"${type}" is declared nowhere for ${system} (${id}) — neither in the master's own locationTypes nor in the built-in ` +
-    `catalog, so the kernel may not include this location in the flow`
+    `catalog. A location whose type is unknown gets no capabilities, so it carries no state, joins no rollup, ` +
+    `and (in domains that move things) may be left out of the flow.`
 })
 
 /**
@@ -595,7 +615,7 @@ export function declaredLocationTypes(productionSpec: unknown): string[] | undef
   return keys.length ? keys : undefined
 }
 
-/** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(조용히 현지 시각으로 가정하지 않는다). */
+/** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(알리지 않고 현지 시각으로 가정하지 않는다). */
 export const unknownTimezone = (timezone: string): IngestWarning => ({
   code: 'unknown-timezone',
   params: { timezone },
@@ -620,7 +640,7 @@ export const noViewableRepresentation = (): IngestWarning => ({
  *
  * 예전에는 이런 참조가 model JSON 안의 맨 문자열이라 화면만 경고할 수 있었고, 다른 경로로 들어온
  * 데이터는 아무도 안 봤다. 이제 행으로 풀면서 **인제스트가 직접 안다** — 그러니 인제스트가 말한다.
- * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 조용히 넘기지 않는다.
+ * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 알리지 않고 넘기지 않는다.
  */
 export const unresolvedReference = (field: string, ref: string): IngestWarning => ({
   code: 'unresolved-reference',
@@ -642,7 +662,7 @@ export const projectionFailed = (reason: string): IngestWarning => ({
  * **동작 중에 공장을 전환했다** — 미러는 멈추지 않으므로, 무엇이 사라졌는지 여기서 말한다.
  *
  * 멈췄다 세우는 구조 전환이라면 사용자가 "다시 세웠다" 는 것을 안다. 미러는 그 마디가 없어서
- * 자리 하나·설비 한 대가 조용히 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
+ * 자리 하나·설비 한 대가 알리지 않고 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
  * 눈치채기를 기대할 수는 없다. 늘어난 것도 함께 말한다(무엇이 반영되었나가 곧 인제스트의 답이다).
  */
 export const structureAdopted = (rev: number, shift: { locationsAdded: number; locationsDropped: number; equipmentDropped: number; personsDropped: number; assetsDropped: number }): IngestWarning => ({
@@ -659,7 +679,7 @@ export const structureAdopted = (rev: number, shift: { locationsAdded: number; l
  *
  * 예: Oracle WMS 가 우리 표에 없는 `locn_type` 을 주면 그 자리는 `storage` 가 된다 — 도크가 랙으로
  * 모델링되는 것이다. 인제스트를 통째로 실패시킬 일은 아니지만(로케이션 하나 때문에 현장 전체가
- * 안 들어오는 편이 더 나쁘다), **조용히 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
+ * 안 들어오는 편이 더 나쁘다), **알리지 않고 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
  * 아무도 그 사실을 모른 채 그 위에서 흐름을 논하게 된다.
  *
  * 값을 나열하는 이유: "3건" 만으로는 커넥터 매핑에 무엇을 더해야 하는지 알 수 없다.
@@ -678,7 +698,7 @@ export const describeWarnings = (warnings: readonly IngestWarning[]): string =>
 /**
  * 서버가 기본값으로 채운 노브들 — 사용자가 준 적 없는 값으로 트윈이 만들어졌음을 알린다.
  *
- * 조용히 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
+ * 알리지 않고 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
  * 확신을 갖고 선언한 값이다) — 다만 밝힌다.
  */
 export const knobDefaultsFilled = (keys: readonly string[]): IngestWarning => ({
@@ -688,7 +708,7 @@ export const knobDefaultsFilled = (keys: readonly string[]): IngestWarning => ({
 })
 
 /**
- * 이 현장의 설비를 노브 값으로 채웠다 — **조용히 채우지 않는다.**
+ * 이 현장의 설비를 노브 값으로 채웠다 — **알리지 않고 채우지 않는다.**
  *
  * 에너지 트윈의 부하를 이웃 설비 id 로 선언할 때 쓴다. 몇 개를 가져왔는지 말해 주지 않으면, 사용자는
  * 자기가 고르지 않은 설비들이 부하로 잡힌 것을 나중에 화면에서야 알게 된다.
@@ -722,14 +742,14 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
     /*
      * **속성도 통과시킨다** — 설비와 같은 규율(손대지 않고 나른다). 여기가 없으면 자리에 실은 값이
      * 커널에 닿지 않는다: 에너지의 계약전력(`contract.kW`)이 그 경로이고, 통과하지 않으면 커널이
-     * 계약을 모르는 채로 서서 **판정을 아예 하지 않는다**(오류 없이 조용히).
+     * 계약을 모르는 채로 서서 **판정을 아예 하지 않는다**(오류 없이 알리지 않고).
      */
     return { id: l.id, type: l.type, ...(l.name ? { name: l.name } : {}), ...(l.description ? { description: l.description } : {}), capacity: l.capacity ?? 0, ...(l.parallelism !== undefined ? { parallelism: l.parallelism } : {}), ...(l.level ? { level: l.level } : {}), ...(l.properties?.length ? { properties: l.properties } : {}), parentId: l.parentId, ...(l.upstreamId ? { upstreamId: l.upstreamId } : {}), gs1Id: l.gs1Id }
   })
 
   const equipment = (master.equipment ?? []).map(e => ({
     id: e.id, kind: e.kind, ...(e.name ? { name: e.name } : {}), ...(e.description ? { description: e.description } : {}), ...(e.testResults?.length ? { testResults: e.testResults } : {}),
-    homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, gs1Id: e.gs1Id,
+    homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, ...(e.identity ? { identity: e.identity } : {}),
     ...(e.window ? { window: e.window } : {}),
     /* 속성은 손대지 않고 통과 — 이동시간 추정기가 kind 별 속도를 여기서 읽는다(단위 코드 그대로). */
     ...(e.properties?.length ? { properties: e.properties } : {}), ...(e.workCalendar?.length ? { workCalendar: e.workCalendar } : {}), ...(e.testSpecificationIds?.length ? { testSpecificationIds: e.testSpecificationIds } : {}),
@@ -831,11 +851,22 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
   // 표현을 안 줘도 geo 만 있으면 위성 지도로 착지. (area 폴리곤 물질화는 좌표 투영 필요 → space #3.)
   const geo = master.space.geo
   const givenReps = master.space.representations ?? []
+  /*
+   * ── 이름을 지어내지 않는다 (2026-08-26) ────────────────────────────────────
+   * 여기가 합성한 표현에 `name: '위성 지도'` 를 넣고 있었다. 이 층은 언어 중립이어야 하는데 한국어가
+   * 그대로 저장됐다.
+   *
+   * 낱말 열쇠(`twin.representation.map` 같은 것)를 넣는 길도 있는데 택하지 않았다. **표현의 이름은
+   * 사람이 바꿀 수 있는 값**이고, 바꿀 수 있는 값 안에 열쇠가 들어 있으면 사람이 한 번 고치는 순간
+   * 그 자리만 열쇠가 아니게 되어 규칙이 둘이 된다.
+   *
+   * 그래서 이름을 넣지 않는다. 화면이 종류(`map`)로 부르고, 사람이 붙이면 그때부터 그 이름이다.
+   */
   const representations =
     givenReps.length > 0
       ? givenReps
       : geo
-        ? [{ id: 'r-map', type: 'map', name: '위성 지도', primary: true, center: { lat: geo.lat, lon: geo.lon }, zoom: 17 }]
+        ? [{ id: 'r-map', type: 'map', primary: true, center: { lat: geo.lat, lon: geo.lon }, zoom: 17 }]
         : []
   if (representations.length === 0) {
     warnings.push(noViewableRepresentation())
@@ -853,7 +884,7 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
  * 다시 읽을 사이트를 고른다 — **기억해 둔 사이트 하나만**.
  *
  * 못 찾으면 **첫 사이트로 때우지 않는다**: 다른 현장의 구조를 이 트윈에 덮어쓰는 일이고, 그것은 오류가
- * 아니라 **조용히 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
+ * 아니라 **오류 없이 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
  * 마스터의 정체(`source` = 인스턴스 id)로 찾는 길을 택한다.
  */
 export function pickOriginSite<T extends { siteId: string }>(

package/server/service/reference/reference-resolver.ts

@@ -7,7 +7,7 @@ import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
 import { readRestartPolicy } from '../../engine/restart-policy.js'
-import { readBoardEquipment } from '@operato/twin-kernel'
+import { readBoardEquipment } from '@operato/ops-contract'
 
 import { applyKnobDefaults, filledKnobKeys } from './knob-defaults.js'
 import type { KnobDef } from './template-registry.js'
@@ -244,7 +244,7 @@ export class TwinReferenceResolver {
       /*
        * **어느 현장의 트윈이었나를 지킨다** — 다시 읽기는 구조만 새로 그리는 일이고, 현장 소속은 그때
        * 사람이 고른 것이다. 기억이 없는 옛 트윈은 **지금 있는 현장**을 그대로 쓴다(빈손으로 두면 템플릿
-       * 기본 공간으로 옮겨 간다 — 조용히 현장을 떠나고 그 현장의 값도 잃는다).
+       * 기본 공간으로 옮겨 간다 — 알리지 않고 현장을 떠나고 그 현장의 값도 잃는다).
        */
       const keepSpace = origin.spaceId || inst.spaceId
       /* 다시 읽기는 **구조만** 새로 그린다 — 재기동 정책은 그 트윈의 선언이므로 그대로 지킨다. */
@@ -304,7 +304,7 @@ export class TwinReferenceResolver {
       const tpl = getTemplate(origin.templateId)
       if (!tpl) throw new Error(`unknown template: ${origin.templateId} — this twin cannot be rebuilt`)
       /* 저장해 둔 노브 그대로 다시 짓는다. 기본값을 다시 입히지 않는다 — 그 사이 템플릿의 기본값이
-         바뀌었다면, 사용자가 고르지 않은 값이 조용히 현장을 바꾸게 된다. */
+         바뀌었다면, 사용자가 고르지 않은 값이 알리지 않고 현장을 바꾸게 된다. */
       const { master } = tpl.build(origin.params ?? {})
       master.origin = origin
       return master
@@ -333,7 +333,7 @@ export class TwinReferenceResolver {
      *
      * 이제 ① 기억해 둔 사이트로 곧장 간다(`origin.siteId`) ② 기억이 없는 옛 트윈은 사이트를 살펴
      * **마스터의 정체(=이 인스턴스 id)** 와 견준다. 어느 쪽도 못 찾으면 **첫 사이트로 때우지 않는다** —
-     * 다른 현장의 구조를 이 트윈에 덮는 것은 오류가 아니라 조용히 틀린 공장으로 나타난다.
+     * 다른 현장의 구조를 이 트윈에 덮는 것은 오류가 아니라 오류 없이 틀린 공장으로 나타난다.
      */
     const picked = pickOriginSite(sites, origin)
     if (picked.site) return { ...(await adapter.fetchMaster(cfg, picked.site, onStep)), origin }
@@ -379,8 +379,8 @@ export class TwinReferenceResolver {
       /*
        * **빠진 노브를 서버가 채운다.** 기본값을 아는 곳은 노브 스키마(계약)인데 그것을 적용하는 곳이
        * 위자드뿐이었다 — 그래서 화면을 거치지 않는 호출자(AI·스크립트·API)가 파라미터를 일부만 주면
-       * 템플릿 안에서 발생률이 0 이 되고 **아무것도 하지 않는 트윈**이 조용히 만들어졌다.
-       * 채운 노브 이름은 경고로 함께 돌려준다 — 조용히 채우는 것도 조용히 비우는 것만큼 위험하다.
+       * 템플릿 안에서 발생률이 0 이 되고 **아무것도 하지 않는 트윈**이 알리지 않고 만들어졌다.
+       * 채운 노브 이름은 경고로 함께 돌려준다 — 알리지 않고 채우는 것도 알리지 않고 비우는 것만큼 위험하다.
        */
       const filled = filledKnobKeys(tpl.knobs, params)
       const effective = applyKnobDefaults(tpl.knobs, params)
@@ -400,7 +400,7 @@ export class TwinReferenceResolver {
       /* 고른 현장도 남긴다 — 없으면 다시 읽기가 트윈을 템플릿 기본 공간으로 옮겨 버린다(현장 값도 잃는다). */
       master.origin = { kind: 'template', templateId, params: effective, ...(spaceId ? { spaceId } : {}) }
       /* 공간 선택은 템플릿을 거치지 않는다 — 템플릿마다 이 노브를 알고 있어야 한다면 새 템플릿이
-         조용히 무시하게 된다. 합성된 마스터에 한 곳에서 얹는다(레퍼런스 인제스트와 같은 경로). */
+         알리지 않고 무시하게 된다. 합성된 마스터에 한 곳에서 얹는다(레퍼런스 인제스트와 같은 경로). */
       const res = await TwinEngine.ingestMaster(
         domainId,
         master,
@@ -638,7 +638,7 @@ export class TwinReferenceResolver {
   @Query(returns => ScalarObject, { description: 'Discover sites/factories exposed by a reference. Returns { sites, error? } — an empty list with no error means the system genuinely has none, which is different from a failure.' })
   async discoverReferenceSites(@Arg('source') source: string, @Ctx() context: ResolverContext): Promise<any> {
     /*
-     * **"못 찾았다" 와 "없다" 를 구분한다.** 예전에는 넷을 빈 배열 하나로 접었고(레퍼런스 없음·어댑터
+     * **"못 찾았다" 와 "없다" 를 구분한다.** 예전에는 넷을 빈 배열 하나로 합쳤고(레퍼런스 없음·어댑터
      * 미상·조회 실패·정말 0건), 화면은 그 모두를 "사이트를 찾지 못했습니다" 라고만 말했다. 실 시스템
      * 연결에서 가장 자주 막히는 자리인데 자격이 틀렸는지 주소가 틀렸는지 알 수 없었다.
      * 판정과 문장 형태는 `discovery-result`(순수)가 갖는다.
@@ -650,7 +650,7 @@ export class TwinReferenceResolver {
     try {
       /*
        * **기다려도 답이 없으면 사유를 준다.** 어댑터 계약에 시간 제한이 없어서, 주소가 틀린 엔드포인트는
-       * 화면을 무한히 돌게 만들었다 — 무한히 도는 화면은 조용한 실패의 다른 얼굴이다.
+       * 화면을 무한히 돌게 만들었다 — 무한히 도는 화면은 들어온 것이 없는 실패의 다른 얼굴이다.
        * 상한은 여기서 정한다(어댑터마다 다르게 두면 사용자가 어느 것을 기다리는지 알 수 없다).
        */
       const sites = await withTimeout(adapter.discoverSites(ref.connectionConfig ?? {}), DISCOVER_TIMEOUT_MS)
@@ -672,7 +672,7 @@ export class TwinReferenceResolver {
    * 데이터로는 가능한 일이 저작으로는 불가능한, `ingest-space` 가 이미 지적한 그 비대칭이다.
    *
    * 판정은 그 순수 모듈이 갖는다: 없는 공간은 거절(`resolveIngestSpace`), 사이트 여럿을 한 공간에
-   * 넣는 것도 거절(`refuseImportSpace`) — 서로 다른 현장이 조용히 합쳐지는 것을 막는다.
+   * 넣는 것도 거절(`refuseImportSpace`) — 서로 다른 현장이 알리지 않고 합쳐지는 것을 막는다.
    */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, {
@@ -762,7 +762,7 @@ export class TwinReferenceResolver {
           /*
            * 정책은 **선언이거나 의도에서 곧바로 따라오는 것**이다: `live=true` 는 미러를 띄우겠다는 뜻이고
            * 미러는 정의상 `resync` 다(외부가 진실이므로 우리 과거를 이어 붙이지 않는다). 시뮬로 띄우려면
-           * 스스로 선언해야 한다 — 그 자리에서 우리가 고르면 재기동마다 이력을 지우는 트윈이 조용히 생긴다.
+           * 스스로 선언해야 한다 — 그 자리에서 우리가 고르면 재기동마다 이력을 지우는 트윈이 알리지 않고 생긴다.
            */
           assessments[site.siteId] = assessMaster(master, site.siteId)
           const policy = readRestartPolicy(restartPolicy ?? (live ? 'resync' : undefined), `importTwinReference("${source}")`)

package/server/service/reference/template-registry.ts

@@ -4,7 +4,7 @@
  * 둘 다 같은 인제스트 경로(ingestMaster)로 흐른다 — 원천이 고정이냐 합성이냐만 다르다(board-authoring §10).
  * 앱(operato-twin)이 bootstrap 에서 자기 아키타입을 registerTemplate 한다. 표현(map/image/model) 무관.
  */
-import type { DomainSystem } from '@operato/twin-kernel'
+import type { DomainSystem } from '@operato/ops-contract'
 
 import type { ReferenceMaster } from './reference-master.js'
 

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

@@ -73,7 +73,7 @@ export class TwinReference {
   /**
    * 마지막 동기에서 **못 옮긴 값의 수**. `null` = 세지 않았다(0 과 다르다).
    *
-   * 세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 조용히 성공한다. 그 사실을 사후에 물을 수
+   * 세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 성공이라 답하면서 아무 일도 하지 않는다. 그 사실을 사후에 물을 수
    * 있어야 단계 판정이 「구조는 됐다」를 말할 수 있다 — 없는 동안 판정은 늘 `unmeasured` 였다.
    * 기본값을 두지 않는다: 0 을 기본으로 깔면 「경고 없었다」와 「세지 않았다」가 같아진다.
    */
@@ -91,10 +91,10 @@ export class TwinReference {
    *
    * 커널이 그 갈림을 이미 적어 두었다(§`hydrateContinuity`): 「원천이 애초에 다시 말해 주지 않는 축」은
    * 재기동 연속성으로 이어받는다. 「우리가 어디까지 읽었나」가 정확히 그 성질이므로 **어댑터의 사물함이
-   * 아니라 이 층**에 있다 — 원본이 늘 때마다 저장 기제가 늘고 그중 하나가 조용히 다르게 동작하지 않게.
+   * 아니라 이 층**에 있다 — 원본이 늘 때마다 저장 기제가 늘고 그중 하나가 알리지 않고 다르게 동작하지 않게.
    *
    * ── 왜 캐시가 아니라 표인가 ────────────────────────────────────────────────
-   * 만료되면 창이 다시 미끄러지고, 그 손실은 오류 없이 조용하다. 스냅샷 체크포인트와 성질이 다르다
+   * 만료되면 창이 다시 미끄러지고, 그 손실은 오류 없이 들어온 것이 없다. 스냅샷 체크포인트와 성질이 다르다
    * (그쪽은 잃어도 원천이 정정해 준다 — 이 값은 **잃으면 원천에 묻지 않게 된다**).
    *
    * 모양은 `{ streams: { [흐름]: { since?, seen[] } }, firstAttachedAt? }` 다. **흐름 이름은 어댑터가

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

@@ -43,7 +43,7 @@ export class TwinAttentionQuery {
 
   /**
    * 잘랐다면 **몇 건을 잘랐는지**와 자리 색 요약까지 — 목록만 주면 화면이 "N건 더" 를 말할 수 없다.
-   * 자리별 최고 심각도는 **전량을 근거로** 접는다(상위 N 으로 접으면 20위 밖 신호를 가진 자리가 색을 잃는다).
+   * 자리별 최고 심각도는 **전량을 근거로** 계산한다(상위 N 으로 줄이면 20위 밖 신호를 가진 자리가 색을 잃는다).
    */
   @Query(returns => ScalarObject, {
     description: 'Attention signals for a space (all its lenses) or one twin, with the total count and the per-location highest severity folded from all of them.'

package/server/service/twin-audit/command-audit.ts

@@ -21,7 +21,7 @@ export type CommandAuditInput = {
    * **원본(어댑터)이 준 답** — 허락과 일어남 사이에 끼어 있는 것을 같은 기록에 닫는다 (ADR-0029 §1 결정 C).
    *
    * ── 왜 이 칸이 필요한가 ──────────────────────────────────────────────────
-   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 조용히 실패하면 원장에는 승인만
+   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 오류 없이 실패하면 원장에는 승인만
    * 남는다. 그래서 어댑터의 답을 **같은 행**에 되적는다.
    *
    * 셋을 구별한다:

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

@@ -103,7 +103,7 @@ export class TwinAuditEvent {
    * **원본이 그래서 어떻게 했나** — 허락과 일어남 사이에 끼어 있는 것을 같은 행에 닫는다
    * (ADR-0029 §1 결정 C, 2026-08-19).
    *
-   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 조용히 실패하면 원장에는 승인만
+   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 오류 없이 실패하면 원장에는 승인만
    * 남는다. 그래서 어댑터의 답을 되적는다.
    *
    *  · 비어 있음 — **원본에 묻지 않았다**(커널이 받은 명령이다). 「모른다」와 다르다.
@@ -142,7 +142,7 @@ export class TwinAuditEvent {
 
   /**
    * 명령 인자 — **원형 그대로.** 무엇에 대한 명령이었는지가 감사의 핵심이라 요약하지 않는다.
-   * 지나치게 크면 자르되 `argsTruncated` 로 잘랐다는 사실을 남긴다(조용히 버리지 않는다).
+   * 지나치게 크면 자르되 `argsTruncated` 로 잘랐다는 사실을 남긴다(알리지 않고 버리지 않는다).
    */
   @Column({ type: 'simple-json', nullable: true })
   @Field(type => ScalarObject, { nullable: true, description: 'Command arguments as given.' })

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

@@ -46,7 +46,7 @@ export class TwinAuditQuery {
       ...(params ?? ({} as ListParam)),
       /* 기본 정렬 — 최근 것부터. 감사는 "요즘" 에서 시작한다. */
       sortings: params?.sortings?.length ? params.sortings : [{ name: 'eventTime', desc: true }],
-      /* 시각 필터는 날짜로 옮겨서 넘긴다 — 문자열 그대로면 조용히 0건이 된다(저널과 같은 이유). */
+      /* 시각 필터는 날짜로 옮겨서 넘긴다 — 문자열 그대로면 알리지 않고 0건이 된다(저널과 같은 이유). */
       filters: (params?.filters ?? []).map(f => (f.name === 'eventTime' ? { ...f, value: toDateValue(f.value) } : f))
     }
 

package/server/service/twin-backfill/backfill-period-facts.ts

@@ -0,0 +1,168 @@
+import { getRepository } from '@things-factory/shell'
+
+import { TwinEvent } from '../twin-event/twin-event.js'
+import { TwinEngine } from '../../engine/twin-engine.js'
+import { ingestCanonicalRecords } from '../../engine/canonical-ingest.js'
+import { absoluteTime } from '../../engine/read-time.js'
+import { judgeBackfill, splitAlreadyThere } from './backfill-shape.js'
+
+/*
+ * 지난 기록 채우기 — **저널에만 쓴다. 트윈의 「지금」을 건드리지 않는다.**
+ *
+ * ── 왜 라이브 문으로 넣을 수 없나 (2026-08-30) ──────────────────────────────
+ * 커널의 상태는 「지금」이다. 늦게 온 옛 표본은 가드가 막는다(그렇게 만들었다). 지난 기록을 라이브
+ * 문으로 넣으면 둘 중 하나다 — 가드에 막히거나, 트윈의 시계가 과거로 끌린다. 둘 다 나쁘다.
+ *
+ * 그래서 이 길은 저널에만 쓴다. 상태는 그대로 두고, 저널을 읽는 쪽(성과 계산·이력 화면)만 그 사실을
+ * 보게 된다.
+ *
+ * ── 무엇을 받나 ────────────────────────────────────────────────────────────
+ * **마감된 구간 사실만** 받는다. 시점의 관측(계량 표본·설비 상태·발전 적산)은 받지 않는다 — 그것들은
+ * 커널의 상태를 바꾸는 사실이라, 상태를 건너뛰고 저널에만 넣으면 상태와 저널이 갈라진다.
+ *
+ * ── 같은 기간을 두 번 넣지 않는다 ──────────────────────────────────────────
+ * 마감된 구간 사실은 정체성이 내용에 있다(커널 0.7.81: 종류·대상·시작·끝). 그 id 로 이미 있는 것을
+ * 가려낸다. 저장소의 제약으로 막지 않는 이유는 드라이버가 다섯이고 충돌 처리가 제각각이기 때문이다 —
+ * 구간 단위로 한 번 읽어 가려내는 편이 이식성이 있고 값도 싸다(한 시간에 한 줄이면 하루 24줄이다).
+ *
+ * ── 보존보다 오래된 것은 받지 않는다 ───────────────────────────────────────
+ * 저널은 보존 기간이 지나면 지운다. 그보다 오래된 것을 채우면 다음 정리에서 지워진다. 조용히 넣고
+ * 지워지면 아무도 모르므로, **거절하고 이유를 말한다.**
+ */
+
+export interface BackfillResult {
+  /** 저널에 새로 적은 수. */
+  written: number
+  /** 이미 있어서 건너뛴 수 — 다시 읽어도 중복이 쌓이지 않는다는 뜻이다. */
+  skipped: number
+  /** 받지 않은 것과 그 이유. 조용히 버리지 않는다. */
+  refused: { record: unknown; reason: string }[]
+}
+
+/** 이 도메인의 보존 기간(일). 정책이 없으면 `undefined` — 그때는 오래됨을 판정하지 않는다. */
+async function retentionDaysOf(domainId: string): Promise<number | undefined> {
+  const perDomain = TwinEngine.retentionDaysOf ? await TwinEngine.retentionDaysOf(domainId).catch(() => undefined) : undefined
+  const days = perDomain ?? TwinEngine.JOURNAL_RETENTION_DAYS
+  return days && days > 0 ? days : undefined
+}
+
+/**
+ * 지난 기록을 저널에 채운다.
+ *
+ * `records` 는 라이브와 **같은 모양**이다 — 커넥터가 다른 어휘를 배울 필요가 없다. 검증·갈림·id 만들기는
+ * 커널의 유입이 그대로 한다(§`ingestCanonicalRecords`).
+ */
+export async function backfillPeriodFacts(input: {
+  domainId: string
+  instanceId: string
+  records: unknown[]
+  /** 이 시각을 「지금」으로 본다 — 보존 판정의 기준. 시험이 시각을 정할 수 있게 받는다. */
+  nowMs?: number
+}): Promise<BackfillResult> {
+  const { domainId, instanceId, records } = input
+  const nowMs = input.nowMs ?? Date.now()
+  const refused: { record: unknown; reason: string }[] = []
+
+  if (!Array.isArray(records) || !records.length) return { written: 0, skipped: 0, refused }
+
+  /* 검증과 갈림은 라이브와 같은 것을 쓴다 — 두 벌이 되면 채운 사실과 관측한 사실이 다른 규칙을 지난다. */
+  const { accepted, rejected } = ingestCanonicalRecords(
+    records as any,
+    domainId,
+    new Date(nowMs).toISOString(),
+    /* 어느 트윈의 사실인가 — 마감된 구간의 이름이 이것으로 갈린다(커널 §`SubjectBasis`). */
+    TwinEngine.factScope(domainId, instanceId)
+  )
+  for (const r of rejected) refused.push({ record: r.record, reason: (r.errors ?? []).join(' · ') })
+
+  const days = await retentionDaysOf(domainId)
+
+  const judged = judgeBackfill(accepted as any[], { nowMs, retentionDays: days })
+  refused.push(...judged.refused)
+  const keep = judged.keep
+
+  if (!keep.length) {
+    TwinEngine.recordIngestResult(
+      domainId,
+      instanceId,
+      records.length,
+      refused.map(r => ({ record: r.record, errors: [r.reason] })),
+      nowMs,
+      0
+    )
+    return { written: 0, skipped: 0, refused }
+  }
+
+  /*
+   * 이미 있는 것을 가려낸다 — 그 구간의 그 종류만 읽는다(색인이 받쳐 준다). 페이로드의 id 로 견주고,
+   * 저장소 제약에 기대지 않는다(드라이버 다섯).
+   */
+  const times = keep.map(e => absoluteTime(e.eventTime)!.getTime())
+  const fromAt = new Date(Math.min(...times))
+  const toAt = new Date(Math.max(...times))
+  const types = [...new Set(keep.map(e => String(e.eventType)))]
+
+  const existing = await getRepository(TwinEvent)
+    .createQueryBuilder('e')
+    .select(['e.payload AS "payload"'])
+    .where('e.domain = :domainId', { domainId })
+    .andWhere('e.instanceId = :instanceId', { instanceId })
+    .andWhere('e.eventType IN (:...types)', { types })
+    .andWhere('e.eventTime BETWEEN :fromAt AND :toAt', { fromAt, toAt })
+    .getRawMany<{ payload: unknown }>()
+
+  const seen = new Set<string>()
+  for (const row of existing) {
+    const p: any = typeof row.payload === 'string' ? safeParse(row.payload) : row.payload
+    const id = p?.eventId
+    if (typeof id === 'string' && id) seen.add(id)
+  }
+
+  const { fresh, skipped } = splitAlreadyThere(keep, seen)
+  if (!fresh.length) {
+    TwinEngine.recordIngestResult(
+      domainId,
+      instanceId,
+      records.length,
+      refused.map(r => ({ record: r.record, errors: [r.reason] })),
+      nowMs,
+      skipped
+    )
+    return { written: 0, skipped, refused }
+  }
+
+  /*
+   * 리비전은 **쓴 순서**다(일어난 순서가 아니다). 지난 사실이 지금 번호를 받는 것이 맞다 — 저널을
+   * 시각으로 읽는 쪽은 `eventTime` 을 보고, 리비전은 같은 시각을 가릴 때만 쓴다.
+   */
+  const start = TwinEngine.journalHead(domainId, instanceId)
+  const items = fresh.map((event, i) => ({ event, revision: start + i + 1 }))
+
+  await TwinEngine.persistCarried(domainId, instanceId, items)
+  TwinEngine.advanceJournalHead(domainId, instanceId, items.length)
+
+  /*
+   * 장부에 적는다 — **유입을 부르는 곳은 모두 적는다.** 한 경로만 빠지면 그 트윈의 유입 건강이
+   * 「모름」으로 보인다(§`ingest-health-wiring`).
+   *
+   * 건네받지 못한 수(`undelivered`)는 **거절한 것과 이미 있어서 건너뛴 것의 합**이다. 건너뛴 것은
+   * 버려진 것이 아니지만 이번에 새로 적히지도 않았다 — 「통과」로 세면 채운 양이 실제보다 커 보인다.
+   */
+  TwinEngine.recordIngestResult(
+    domainId,
+    instanceId,
+    records.length,
+    refused.map(r => ({ record: r.record, errors: [r.reason] })),
+    nowMs,
+    skipped
+  )
+  return { written: items.length, skipped, refused }
+}
+
+function safeParse(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}

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 }
+}