@things-factory/headless-twin 10.0.14 → 10.0.17

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

@@ -118,7 +118,7 @@ export interface RefTestResult {
   specId: string
   result: 'pass' | 'fail'
   at?: string
-  /** 없으면 무기한 — 짐작으로 기한을 만들면 멀쩡한 자격자가 조용히 사라진다. */
+  /** 없으면 무기한 — 짐작으로 기한을 만들면 멀쩡한 자격자가 오류 없이 사라진다. */
   expiresAt?: string
 }
 
@@ -177,7 +177,7 @@ export interface RefEquipment {
    *
    * 없으면 **폐기한 것이 영구히 살아 있다**: 배정 대상에 남고, 가용 수에 들어가고, 화면에 뜬다.
    * 도입 예정인 것은 반대로 오늘부터 있는 것처럼 보인다. 기간 밖이면 커널이 그 시각의 모델에서
-   * 빼고 **이유를 달아 남긴다**(`effectivity: 'not-yet' | 'expired'`) — 조용히 지우지 않는다.
+   * 빼고 **이유를 달아 남긴다**(`effectivity: 'not-yet' | 'expired'`) — 알리지 않고 지우지 않는다.
    */
   effectiveStart?: string
   effectiveEnd?: string
@@ -226,7 +226,7 @@ export interface RefOperationVariability {
  *
  * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 고정한 상수다.** 원 시스템(또는 가상 레퍼런스)이
  * 공정별 소요·변동·수율을 말해 줘야 예측이 그 현장의 예측이 된다. 주지 않으면 커널 기본값으로
- * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(조용히 넘어가지 않는다).
+ * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(알리지 않고 넘어가지 않는다).
  */
 export interface RefOperation {
   /** 작업 종류 키 — 커널 `FlowTask.kind` 와 같은 값이어야 명세가 그 작업에 붙는다. */
@@ -366,7 +366,7 @@ export type MasterOrigin =
   /**
    * 템플릿 + 노브로 합성했다 — 다시 읽기 = 같은 노브로 다시 짓는다(합성은 결정적이다).
    *
-   * `spaceId` 는 **만들 때 고른 현장**이다(합쳐 넣기). 기억하지 않으면 다시 읽을 때 트윈이 조용히 자기
+   * `spaceId` 는 **만들 때 고른 현장**이다(합쳐 넣기). 기억하지 않으면 다시 읽을 때 트윈이 알리지 않고 자기
    * 현장을 떠난다 — 템플릿이 낸 기본 공간으로 돌아가기 때문이다. 그러면 그 현장의 값(요금 등)도 함께
    * 잃는다(2026-08-18 실측: 한 현장에 합쳐 둔 EMS 트윈 여덟이 재동기 뒤 각자 공간으로 흩어졌다).
    */
@@ -457,7 +457,7 @@ export interface ReferenceMaster {
    * 여기에 담아 보낸다 — 그러면 `masterToTwin` 의 경고와 한 줄기로 합쳐져 화면까지 간다.
    *
    * 이 자리가 없던 동안 커넥터는 할 말이 있어도 **말할 곳이 없었다.** 그래서 도크를 랙으로 바꿔
-   * 놓고도 조용히 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
+   * 놓고도 알리지 않고 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
    */
   warnings?: IngestWarning[]
   /**
@@ -498,7 +498,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 +553,7 @@ export interface IngestWarning {
  * 형상은 **시각별 비율**이라, 시간대가 없으면 현장 정오가 아니라 UTC 정오에 피크가 선다(KST 현장이면
  * 밤 9시). 값이 그럴듯하게 나오므로 아무도 알아채지 못한다.
  *
- * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 조용히
+ * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 알리지 않고
  * 그 가정 위에 선다) 대신 **그 조합을 말한다** — 공간에 시간대를 선언하면 사라지는 경고다.
  */
 export const generationWithoutTimeZone = (spaceId: string, equipmentId: string): IngestWarning => ({
@@ -576,9 +576,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 +606,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 +631,7 @@ export const noViewableRepresentation = (): IngestWarning => ({
  *
  * 예전에는 이런 참조가 model JSON 안의 맨 문자열이라 화면만 경고할 수 있었고, 다른 경로로 들어온
  * 데이터는 아무도 안 봤다. 이제 행으로 풀면서 **인제스트가 직접 안다** — 그러니 인제스트가 말한다.
- * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 조용히 넘기지 않는다.
+ * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 알리지 않고 넘기지 않는다.
  */
 export const unresolvedReference = (field: string, ref: string): IngestWarning => ({
   code: 'unresolved-reference',
@@ -642,7 +653,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 +670,7 @@ export const structureAdopted = (rev: number, shift: { locationsAdded: number; l
  *
  * 예: Oracle WMS 가 우리 표에 없는 `locn_type` 을 주면 그 자리는 `storage` 가 된다 — 도크가 랙으로
  * 모델링되는 것이다. 인제스트를 통째로 실패시킬 일은 아니지만(로케이션 하나 때문에 현장 전체가
- * 안 들어오는 편이 더 나쁘다), **조용히 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
+ * 안 들어오는 편이 더 나쁘다), **알리지 않고 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
  * 아무도 그 사실을 모른 채 그 위에서 흐름을 논하게 된다.
  *
  * 값을 나열하는 이유: "3건" 만으로는 커넥터 매핑에 무엇을 더해야 하는지 알 수 없다.
@@ -678,7 +689,7 @@ export const describeWarnings = (warnings: readonly IngestWarning[]): string =>
 /**
  * 서버가 기본값으로 채운 노브들 — 사용자가 준 적 없는 값으로 트윈이 만들어졌음을 알린다.
  *
- * 조용히 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
+ * 알리지 않고 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
  * 확신을 갖고 선언한 값이다) — 다만 밝힌다.
  */
 export const knobDefaultsFilled = (keys: readonly string[]): IngestWarning => ({
@@ -688,7 +699,7 @@ export const knobDefaultsFilled = (keys: readonly string[]): IngestWarning => ({
 })
 
 /**
- * 이 현장의 설비를 노브 값으로 채웠다 — **조용히 채우지 않는다.**
+ * 이 현장의 설비를 노브 값으로 채웠다 — **알리지 않고 채우지 않는다.**
  *
  * 에너지 트윈의 부하를 이웃 설비 id 로 선언할 때 쓴다. 몇 개를 가져왔는지 말해 주지 않으면, 사용자는
  * 자기가 고르지 않은 설비들이 부하로 잡힌 것을 나중에 화면에서야 알게 된다.
@@ -722,7 +733,7 @@ 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 }
   })
@@ -831,11 +842,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 +875,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

@@ -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/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-control/twin-control-mutation.ts

@@ -50,7 +50,7 @@ export class TwinControlMutation {
      * 증명할 수 있다. 커널이 거절한 것도 남긴다 — 무엇을 시도했는지가 감사의 절반이다.
      *
      * 기록이 실패해도 커맨드 결과는 그대로 돌려준다. 감사가 본업을 막으면 안 되지만, 실패를 삼키지도
-     * 않는다(로그에 남긴다) — 조용히 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
+     * 않는다(로그에 남긴다) — 알리지 않고 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
      */
     try {
       const audit = buildCommandAudit({ command: cmdWithOrigin, ack, actor: context.state.user, at: new Date() })

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

@@ -29,7 +29,7 @@ export interface TwinEventKeys {
 
 /*
  * 컬럼 길이 상한. GS1 식별자(EPC URN·GDTI·SGLN)는 규격상 이보다 훨씬 짧다.
- * 넘치는 값이 오면 **조용히 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,
+ * 넘치는 값이 오면 **알리지 않고 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,
  * 그 사실이 어디에도 안 남으면 아무도 모른다.
  */
 const MAX_KEY = 255
@@ -65,10 +65,30 @@ export function epcOf(envelope: any): string | undefined {
   return d.epcList?.[0] ?? d.parentID ?? d.quantityList?.[0]?.epcClass ?? undefined
 }
 
-/** 거래 식별자(PO/SO) — EPCIS bizTransactionList 우선, 운영 델타는 `order`. */
+/**
+ * 오더 식별자 — 운영 델타의 `orderId` 우선, EPCIS 는 `bizTransactionList`.
+ *
+ * ── 실측 (2026-08-24) — 이 컬럼이 **전부 비어 있었다** ──────────────────────
+ * 여기가 찾던 이름이 `d.order` 였다. 그런데 커널이 내는 이름은 **`orderId`** 다
+ * (`OrderStatusDelta.orderId` · `TaskStatusDelta.orderId`). `d.order` 를 내는 코드는 커널에 **한 곳도
+ * 없다** — 죽은 가지였다. 그래서 운영 델타는 이 컬럼을 한 번도 채우지 못했다.
+ *
+ *   order.status   29,403,565 행 — order_id 비어 있음 29,403,565 (100%)
+ *   task.status       191,175 행 — 비어 있음 191,175 (100%)
+ *
+ * 그 결과 색인 `ix_twin_event_4` 가 **자기 주석이 적어 둔 용도**(「이 오더가 어디까지 갔나」)로 쓸 수
+ * 없었다. 화면은 오더를 눌러도 「연결된 이벤트가 없습니다」를 냈고, 그 답은 질의 결과로는 정직했다 —
+ * 시점을 어디로 옮겨도 0 이었다.
+ *
+ * 순서가 중요하다: 운영 델타가 먼저다. EPCIS 의 `bizTransactionList` 는 **거래**(PO/SO)이고 오더와
+ * 같은 것이 아닐 수 있으므로, 오더를 스스로 말하는 사건은 그 말을 그대로 쓴다.
+ *
+ * **과거 행은 채워지지 않는다**(사용자 결정 2026-08-24, `moverId` 때와 같은 방식). 앞으로 들어오는
+ * 사건부터 조회된다.
+ */
 export function orderOf(envelope: any): string | undefined {
   const d = envelope?.data ?? envelope ?? {}
-  return d.bizTransactionList?.[0]?.bizTransaction ?? d.order ?? undefined
+  return d.orderId ?? d.bizTransactionList?.[0]?.bizTransaction ?? undefined
 }
 
 /**
@@ -89,14 +109,26 @@ export function locationOf(envelope: any): string | undefined {
  */
 export function equipmentIdOf(envelope: any): string | undefined {
   const d = envelope?.data ?? envelope ?? {}
-  return d.moverId ?? undefined
+  /*
+   * ── 실측 (2026-08-24) — 두 갈래를 놓치고 있었다 ────────────────────────────
+   * 위 주석이 `task.status` 를 출처로 **적어 두었는데** 이 함수는 `d.moverId` 만 봤다. 작업이 자원을
+   * 가리키는 이름은 `resourceRef` 다(`TaskStatusDelta.resourceRef`) — 그래서 작업 191,175 행 전부
+   * 이 컬럼이 비었고, 「이 지게차가 오늘 무엇을 했나」에서 **작업이 통째로 빠졌다.**
+   *
+   * 그리고 에너지 사건은 `equipmentId` 를 쓴다(어휘가 `movers`→`equipment` 로 개명된 뒤에 생긴
+   * 채널이다). 실측 `energy.equipment` 31,079 행 전부 비어 있었다 — 「이 설비가 얼마를 먹었나」를
+   * 설비 축으로 물을 수 없었다.
+   *
+   * 셋을 함께 본다. 개명 세대가 섞여 있는 것은 저널의 성질이고, 읽는 쪽이 그것을 흡수한다.
+   */
+  return d.moverId ?? d.resourceRef ?? d.equipmentId ?? undefined
 }
 
 /**
  * EPCIS 행위 — `ADD`·`OBSERVE`·`DELETE`. 세 값이 아니면 `undefined`(원천의 잡값을 색인에 넣지 않는다).
  *
  * 이 키는 검색 축이 아니라 **판별식**이다: 되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다.
- * 그래서 「이 트윈이 반출을 한 번이라도 접었는가」가 진짜 delta 피드의 증거인데, payload 안에 있는
+ * 그래서 「이 트윈이 반출을 한 번이라도 계산했는가」가 진짜 delta 피드의 증거인데, payload 안에 있는
  * 동안에는 5개 드라이버 어디에서도 그 질문을 할 수 없었다. 운영 델타에는 행위가 없다 — 비운다.
  */
 export function actionOf(envelope: any): string | undefined {

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

@@ -6,7 +6,7 @@ import { TwinEvent } from './twin-event.js'
  * 저널 목록 반환형 — things-factory 표준 `{ items, total }`(AttributeSetList·DomainList 등과 동형).
  *
  * `total` 이 이 타입의 존재 이유다. 기존 `twinEvents` 는 배열만 돌려줘서 **화면이 자기가 전체를 받은
- * 건지 잘린 건지 알 방법이 없었다** — 그래서 리스트가 조용히 잘린 채로 "이게 전부" 처럼 보였다.
+ * 건지 잘린 건지 알 방법이 없었다** — 그래서 리스트가 알리지 않고 잘린 채로 "이게 전부" 처럼 보였다.
  * 총건수를 함께 주면 화면은 "48 / 12,904" 라고 정직하게 말할 수 있고, 사용자는 좁혀야 한다는 걸 안다.
  */
 @ObjectType({ description: 'A page of twin journal events together with the total number of matching records.' })
@@ -48,4 +48,21 @@ export class TwinEventList {
    */
   @Field({ nullable: true, description: 'Opaque cursor for the next page. Pass it back as pagination.after to continue exactly where this page ended, without the duplicate or skipped rows that offset paging produces on a journal that keeps growing at the head. Null when this page is the last one.' })
   nextCursor?: string
+
+  /*
+   * **앞부분이 지워졌다** — 보관 기간 정리가 이 트윈의 오래된 사건을 지운 경우 (2026-08-27).
+   *
+   * 정리는 선언된 보관 기간(기본 7일)보다 오래된 사건을 지운다. 그러면 이 목록의 첫 페이지 뒤로 더
+   * 내려가도 어느 지점에서 기록이 끝난다. 화면이 그것을 말하지 않으면 사람은 「이 트윈은 그때부터
+   * 시작했다」로 읽는다. 없었던 것과 지워진 것은 다른 사실이다.
+   *
+   * 값은 저장하지 않고 조회할 때 구한다(남아 있는 가장 작은 리비전). 저장하면 실제 데이터와 어긋날 수
+   * 있고, 어긋나면 어느 쪽이 사실인지 알 수 없다.
+   */
+  @Field(type => Int, {
+    nullable: true,
+    description:
+      'The oldest revision still stored for this twin. When it is greater than 1, older events were deleted by the journal retention policy: the screen must say the record starts here rather than implying the twin began at this point. NULL when the caller asked for more than one twin (the axis is per twin) or when nothing is stored.'
+  })
+  oldestRevision?: number
 }

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

@@ -34,8 +34,34 @@ import { Domain, ScalarObject } from '@things-factory/shell'
 @Index('ix_twin_event_4', (e: TwinEvent) => [e.domain, e.instanceId, e.orderId], { unique: false })
 /* ix_5 — "이 지시가 무엇을 일으켰나". 감사 기록의 commandId 로 저널을 다시 계산하는 축. */
 @Index('ix_twin_event_5', (e: TwinEvent) => [e.domain, e.correlationId], { unique: false })
-/* ix_6 — "반출을 한 번이라도 접었나". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */
+/* ix_6 — "반출을 한 번이라도 계산했나". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */
 @Index('ix_twin_event_6', (e: TwinEvent) => [e.domain, e.instanceId, e.action], { unique: false })
+/*
+ * ix_7 — **"이 종류의 사실을 시각순으로"** (2026-08-25 실측으로 추가)
+ *
+ * 이 축이 없어서 공정 타임라인이 22초였다. 종류로 거르고 시각으로 정렬하는 조회가 갈 곳이 없었다:
+ *
+ *   ix_2 (…, eventType, revision)   종류는 걸러지고 정렬이 **적힌 순서**다 → 4월 사실을 최근으로 그렸다
+ *   ix_1 (…, eventTime)             정렬은 맞고 **종류를 못 거른다** → 행마다 테이블을 열어 확인한다
+ *
+ * 뒤쪽으로 걸으면 그 트윈에서 찾는 종류가 멈춘 시점까지의 모든 행을 읽고 버린다. 승화푸드에서 작업
+ * 사실은 8월 22일에 멈춰 있고 그 뒤로 리비전이 110만 늘었으므로, 200건에 닿기까지 110만 행을 열었다.
+ *
+ * 위 주석이 「측정을 근거로 추가할 일이지 지레 얹을 일은 아니다」라고 적어 두었다. 그 측정이 나왔다.
+ */
+@Index('ix_twin_event_7', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.eventTime], { unique: false })
+/*
+ * ix_8 — **"이 트윈의 오래된 기록"** (2026-08-27 실측으로 추가)
+ *
+ * 보관 기간 정리가 `created_at` 으로 자르는데(보관은 저장 나이의 문제다) 그 축에 인덱스가 없었다.
+ * 그래서 정리가 매 배치마다 그 트윈의 저널을 전량 주사했다.
+ *
+ *   hatio-mx2 의 7일 밖 행을 세기      208초   ← 1,029만 행을 전부 읽는다(7일 밖은 2,446건뿐이다)
+ *   revision 으로 한 행 짚기           0.004초
+ *
+ * 정리는 한 창에 2초만 쓰도록 예산이 걸려 있어서, 그 2초를 주사에 다 쓰고 44건만 지우고 멈췄다.
+ */
+@Index('ix_twin_event_8', (e: TwinEvent) => [e.domain, e.instanceId, e.createdAt], { unique: false })
 @ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 export class TwinEvent {
   @PrimaryGeneratedColumn('uuid')
@@ -71,8 +97,8 @@ export class TwinEvent {
    * 이 사실이 **어느 공장에서** 일어났나 — `TwinStructure.rev`.
    *
    * 이것이 없던 시절에는 구조가 바뀌면 저널을 통째로 지우는 것이 유일한 길이었다(안 지우면 옛
-   * 이벤트를 새 공장에 대고 접어 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이
-   * 구조가 바뀌는 지점에서 전환한 뒤 이어 접는다.
+   * 이벤트를 새 공장에 대고 계산해 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이
+   * 구조가 바뀌는 지점에서 전환한 뒤 이어서 계산한다.
    *
    * **비어 있을 수 있다**: 컬럼이 생기기 전에 쓰인 행이다. 그 행들은 **가장 오래된 리비전**에
    * 속한다(0 을 채워 넣지 않는다 — 0 은 "모름" 이 아니라 유효한 번호처럼 보인다).
@@ -85,7 +111,7 @@ export class TwinEvent {
    * 이 사실이 일어난 시각(트윈의 시계). **날짜 타입이다.**
    *
    * 예전에는 문자열이었다. 읽을 때마다 `Date.parse` 했고, 정렬은 UTC ISO 만 들어온다는 전제 위에서
-   * 사전식 비교가 우연히 맞았다 — `+09:00` 오프셋 표기가 하나 섞이면 조용히 순서가 틀린다.
+   * 사전식 비교가 우연히 맞았다 — `+09:00` 오프셋 표기가 하나 섞이면 알리지 않고 순서가 틀린다.
    * 그 전제는 컬럼 어디에도 적혀 있지 않았다.
    *
    * **타입 이름을 적지 않는다** (2026-08-19 Postgres 부팅 실패로 고침).
@@ -108,11 +134,11 @@ export class TwinEvent {
    * payload 가 여전히 정본이고 이것들은 **파생 색인**이다 — 새로운 진실이 아니라 찾을 수 있게 하는 장치.
    * simple-json(TEXT) 안의 값은 5개 DB 드라이버 공통으로 거를 방법이 없어서(멀티DB 호환 규칙상
    * DB별 JSON 연산자 금지) 승격 외의 선택지가 없다.
-   * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 조용히 잘리지 않고 경고를 남긴다.
+   * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 알리지 않고 잘리지 않고 경고를 남긴다.
    *
    * ── 축을 새로 추가할 때 ──────────────────────────────────────────────────
    * 새 승격 컬럼을 만들면 **이미 쌓인 행은 비어 있다.** 그 행들은 새 축으로 검색되지 않고,
-   * 사용자에게는 "과거가 없는 것" 으로 보인다(조용히 빠진 데이터).
+   * 사용자에게는 "과거가 없는 것" 으로 보인다(알리지 않고 빠진 데이터).
    *
    * 예전에는 기동 훅이 매번 테이블을 살펴 채웠다. 그건 두 가지로 틀렸다 — 저널이 커질수록 부팅이
    * 느려지고, "bizStep 이 비었으면 옛 행" 이라는 전제를 코드에 고정해 그 전제가 깨지는 순간

package/server/service/twin-forecast/forecast-metrics.ts

@@ -3,7 +3,7 @@
  *
  * ── 왜 순수 모듈인가 (2026-08-15) ───────────────────────────────────────────
  * 이 표가 리졸버 안에 있어서 시험이 불러올 수 없었다(type-graphql·shell 을 물고 있다). 그런데 여기서
- * 틀리면 예측 그래프 전체가 조용히 다른 것을 그린다 — 오류 없이. 규칙은 시험이 닿는 자리에 둔다.
+ * 틀리면 예측 그래프 전체가 알리지 않고 다른 것을 그린다 — 오류 없이. 규칙은 시험이 닿는 자리에 둔다.
  *
  * ── 에너지 지표를 더한 이유 ─────────────────────────────────────────────────
  * 예측 화면의 지표가 물류 여섯(재고·점유·작업·오더·출고·백로그)으로 고정돼 있어서, 에너지 트윈을

package/server/service/twin-forecast/gap-analytics.ts

@@ -23,7 +23,7 @@ export interface GapPoint {
   modelAbsError: number
 }
 
-/** 합산 결과 + **무엇을 못 넣었는지.** 조용히 줄이지 않는다. */
+/** 합산 결과 + **무엇을 못 넣었는지.** 알리지 않고 줄이지 않는다. */
 export interface AggregateResult {
   points: GapPoint[]
   /** 한 트윈이라도 재지 못해 통째로 뺀 vantage 수. */