@things-factory/headless-twin 10.0.14 → 10.0.17

package/test/reference-hook.test.ts

@@ -0,0 +1,86 @@
+/*
+ * ★ 연결된 시스템이 밀어 주는 사실을 받는 자리 — 규약을 시험이 지킨다.
+ *
+ * ── 왜 만들었나 (2026-08-26 · 사용자 지시) ──────────────────────────────────
+ * 지금 모든 커넥터가 주기적으로 물어봅니다. 그러면 연결된 시스템이 값을 갱신하는 주기보다 자주 묻게
+ * 되고, 그쪽 서버에 그만큼 부담을 줍니다. 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을
+ * 받아 왔고, 그날 그쪽 서버가 부하로 멈췄습니다.
+ *
+ * ── 무엇을 지키나 ───────────────────────────────────────────────────────────
+ * 응답 코드가 규약입니다. 밀어 주는 쪽은 그 코드로 재시도를 정하므로, 우리가 아무렇게나 주면 고칠 수
+ * 없는 것을 영원히 다시 보내거나, 잠깐의 문제로 사라진 사실을 아무도 모릅니다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { HOOK_STATUS, secretFromHeaders, secretMatches, producedInstance } from '../server/service/reference/hook-contract.js'
+
+test('★ 비밀값을 두 가지 방식으로 받는다 — 밀어 주는 쪽의 관습이 갈린다', () => {
+  assert.equal(secretFromHeaders({ 'x-twin-hook-secret': 'abc' }), 'abc')
+  assert.equal(secretFromHeaders({ authorization: 'Bearer abc' }), 'abc')
+  assert.equal(secretFromHeaders({ authorization: 'bearer  abc ' }), 'abc')
+  assert.equal(secretFromHeaders({}), '')
+  assert.equal(secretFromHeaders(undefined), '')
+})
+
+test('★ 전용 헤더가 먼저다 — 둘 다 오면 헷갈리지 않는다', () => {
+  assert.equal(secretFromHeaders({ 'x-twin-hook-secret': 'first', authorization: 'Bearer second' }), 'first')
+})
+
+test('★ 빈 비밀값은 어떤 것과도 맞지 않는다 — 선언하지 않은 연결은 훅을 받지 않는다', () => {
+  assert.equal(secretMatches('', ''), false)
+  assert.equal(secretMatches('anything', ''), false)
+  assert.equal(secretMatches('', 'expected'), false)
+})
+
+test('★ 비밀값 비교는 길이가 같으면 전부를 본다 — 응답 시간으로 알아내지 못하게', () => {
+  assert.equal(secretMatches('secret-value', 'secret-value'), true)
+  assert.equal(secretMatches('secret-valuX', 'secret-value'), false)
+  assert.equal(secretMatches('Xecret-value', 'secret-value'), false)
+  assert.equal(secretMatches('short', 'secret-value'), false)
+})
+
+test('★ 그 연결이 만든 트윈만 받는다 — 남의 트윈에 밀어 넣지 못한다', () => {
+  const ref = {
+    scopeSpec: {
+      produced: [
+        { siteId: 'site-a', instanceId: 'twin-a' },
+        { siteId: 'site-b', instanceId: 'twin-b' }
+      ]
+    }
+  }
+  assert.deepEqual(producedInstance(ref, 'twin-b'), { siteId: 'site-b' })
+  assert.equal(producedInstance(ref, 'twin-c'), undefined)
+  assert.equal(producedInstance(null, 'twin-a'), undefined)
+  assert.equal(producedInstance({}, 'twin-a'), undefined)
+})
+
+test('★ 응답 코드가 재시도로 풀리는 것과 그렇지 않은 것을 가른다', () => {
+  /*
+   * 재시도해도 같은 것: 비밀값이 다르다 · 모르는 대상 · 옮길 수 없는 본문 · 커넥터가 훅을 모른다
+   * 사람이 손대야 하는 것: 트윈이 돌지 않는다
+   * 재시도하면 될 수 있는 것: 우리 쪽 오류
+   */
+  assert.equal(HOOK_STATUS.ok, 200)
+  assert.equal(HOOK_STATUS.badPayload, 400)
+  assert.equal(HOOK_STATUS.badSecret, 401)
+  assert.equal(HOOK_STATUS.unknownTarget, 404)
+  assert.equal(HOOK_STATUS.notLive, 409)
+  assert.equal(HOOK_STATUS.failed, 500)
+  assert.equal(HOOK_STATUS.unsupported, 501)
+
+  /* 재시도해도 같은 것에 5xx 를 주면 안 된다 — 그쪽이 영원히 다시 보낸다. */
+  for (const code of [HOOK_STATUS.badPayload, HOOK_STATUS.badSecret, HOOK_STATUS.unknownTarget, HOOK_STATUS.notLive]) {
+    assert.ok(code < 500, `${code} 는 4xx 여야 한다`)
+  }
+  /* 우리 쪽 문제에는 5xx 를 준다 — 그쪽이 다시 보내야 그 사실이 살아남는다. */
+  assert.ok(HOOK_STATUS.failed >= 500)
+})
+
+test('★ 트윈이 돌지 않으면 200 을 주지 않는다 — 그쪽이 그 사실을 버린다', () => {
+  /*
+   * 200 은 「받아서 반영했다」는 뜻입니다. 트윈이 실시간으로 돌지 않아 한 건도 반영되지 않았는데
+   * 200 을 주면, 밀어 주는 쪽은 전달된 줄 알고 그 사실을 버립니다. 다시 보내 주지도 않습니다.
+   */
+  assert.notEqual(HOOK_STATUS.notLive, HOOK_STATUS.ok)
+  assert.equal(HOOK_STATUS.notLive, 409)
+})

package/test/registry-key-guard.test.ts

@@ -6,7 +6,7 @@
  * 그래서 도메인 확인이 자리마다 제각각이었고 한 곳은 아예 없었다.
  *
  * 키를 `(domainId, instanceId)` 로 고쳤지만, **직접 색인이 남아 있으면 같은 부류가 다시 자란다** — 밖에서
- * `instances[id]` 를 쓰면 이제는 항상 `undefined` 가 나와 조용히 "안 돌고 있다" 로 읽힌다(더 나쁘다:
+ * `instances[id]` 를 쓰면 이제는 항상 `undefined` 가 나와 알리지 않고 "안 돌고 있다" 로 읽힌다(더 나쁘다:
  * 오류가 아니라 거짓 사실이 된다). 그래서 접근자(`owns`·`runtime`·`kernel`·`metrics`·`snapshot`)만 쓴다.
  *
  * 이 부류는 이미 한 번 물었다 — `twin-lifecycle-mutation.ts` 주석이 증언한다("과거엔

package/test/rename-twin.test.ts

@@ -0,0 +1,81 @@
+/*
+ * ★ 트윈이 첫날의 이름에 갇혀 있었다 — 바꿀 문이 없었다.
+ *
+ * 이름은 처음 세울 때 한 번 정해지고(`provision`) 다시 읽기는 건드리지 않는다. 그 자체는 안전하다 —
+ * 사람이 붙인 이름을 연결이 덮어쓰면 안 된다. 그런데 그래서 첫날 이름에서 벗어날 길이 없었다.
+ *
+ * 실제로 그런 일이 났다(2026-08-25 · 태양광 발전소). 커넥터가 처음 아는 이름이 연결된 시스템의
+ * 코드뿐이었다.
+ *
+ *   현장 이름   호현에너지
+ *   트윈 이름   ES202307202202      ← 화면의 트윈 목록에 이렇게 보였다
+ *
+ * 뒤에 사람이 부르는 이름이 어디 있는지 알아내 커넥터를 고쳤는데, 트윈 이름은 그대로였다. 남은
+ * 유일한 길이 트윈을 지우고 다시 세우는 것이었고, 그러면 그날 실제 발전소에서 받은 246건이
+ * 사라진다 — **이름 하나 때문에 사실을 버리는 선택**이다.
+ *
+ * 연결된 시스템을 따라가는 트윈에서는 이름이 나중에 좋아진다. 커넥터가 나아질 때마다 나는 일이다.
+ *
+ * 이 테스트는 소스를 전수 조회해 규율을 지킨다(실제 뮤테이션은 DB 와 도메인 맥락이 필요하다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const FILE = join(import.meta.dirname, '..', 'server', 'service', 'twin-lifecycle', 'twin-lifecycle-mutation.ts')
+const src = readFileSync(FILE, 'utf8')
+const body = (() => {
+  const at = src.indexOf('async renameTwinInstance')
+  assert.ok(at > 0, '이름을 바꾸는 문이 있어야 한다')
+  return src.slice(at, src.indexOf('async deleteTwinInstance'))
+})()
+
+test('★ 이름을 바꾸는 문이 있다 — 없어서 지우고 다시 세우는 것이 유일한 길이었다', () => {
+  assert.ok(/@Mutation/.test(src.slice(0, src.indexOf('async renameTwinInstance'))))
+  assert.ok(/@Arg\('instanceId'\)/.test(body))
+  assert.ok(/@Arg\('name'\)/.test(body))
+})
+
+test('★ 빈 이름은 받지 않는다 — 지우는 것과 바꾸는 것은 다른 일이다', () => {
+  assert.ok(/\.trim\(\)/.test(body), '앞뒤 공백은 이름이 아니다')
+  assert.ok(/if \(!next\) throw/.test(body), '빈 값이면 거절한다')
+  /* 빈 이름을 받아 두면 그 트윈은 목록에서 식별자만 남는데, 그것을 「바꿨다」로 보고하면 거짓이다. */
+  assert.ok(/left as it was/.test(body), '무엇도 바뀌지 않았다는 것을 말한다')
+})
+
+test('★ 남의 도메인 트윈은 바꾸지 못한다 — 테넌트 격리', () => {
+  assert.ok(/where: \{ domain: \{ id: domainId \}, instanceId \}/.test(body), '도메인으로 좁혀 찾는다')
+  assert.ok(/unknown twin/.test(body), '없으면 이유를 말한다')
+})
+
+test('바꾸지 않은 경우를 바꿨다고 말하지 않는다', () => {
+  assert.ok(/changed: false/.test(body), '같은 이름이면 changed 를 false 로 낸다')
+  assert.ok(/previous/.test(body), '무엇에서 무엇으로 바뀌었는지 함께 낸다')
+})
+
+test('바꾼 사람을 남긴다 — 이름은 사람이 하는 선언이다', () => {
+  assert.ok(/updater: context\.state\.user/.test(body))
+})
+
+test('이름만 바꾼다 — 트윈을 멈추거나 다시 읽지 않는다', () => {
+  /*
+   * 도는 런타임은 식별자로 동작하고 이름을 쓰지 않는다. 정지·기동을 끼우면 그 사이의 사실이 어디로
+   * 갔는지 설명해야 하는데, 이름 때문에 그 값을 치를 이유가 없다.
+   */
+  assert.ok(!/TwinEngine\.(stop|start|remove|resync)/.test(body), '런타임을 건드리지 않는다')
+  assert.ok(!/adoptStructure|reprovision/.test(body), '구조를 다시 읽지 않는다')
+})
+
+test('연결된 시스템이 이름을 덮어쓰지는 않는다 — 다시 읽기는 그대로다', () => {
+  /*
+   * 「사람이 손대지 않았으면 따라간다」가 옳아 보이지만, 그러려면 「손댔다」는 표시를 새로 만들어야
+   * 한다. 이름 하나 때문에 지기에 무거운 빚이므로 사람이 바꾸는 길만 낸다. 그 결정을 여기서 고정한다.
+   *
+   * 이름을 정하는 자리는 **처음 세울 때 하나**다. 그 수가 늘면 다시 읽기가 이름을 다시 정하기
+   * 시작했다는 뜻이고, 그때는 이 결정을 다시 해야 한다.
+   */
+  const engine = readFileSync(join(import.meta.dirname, '..', 'server', 'engine', 'twin-engine.ts'), 'utf8')
+  const places = engine.match(/name: master\.siteName/g) ?? []
+  assert.equal(places.length, 1, `이름을 정하는 자리가 ${places.length}곳이다 — 처음 세울 때 하나여야 한다`)
+})

package/test/restart-policy.test.ts

@@ -8,7 +8,7 @@
  * 이름이 바뀌었다.
  *
  * ── 지키는 규율 둘 (계획서 §6) ──────────────────────────────────────────────
- * ① **모르는 값은 오류를 낸다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다 — 값이
+ * ① **모르는 값은 오류를 낸다.** 예전에는 미선언이 알리지 않고 `sim-experiment`(=저널 초기화)로 떨어졌다 — 값이
  *    하나 어긋나는 순간 이력을 지우는 길이다. 기본값을 없앴다.
  * ② **옛 어휘를 번역하지 않는다.** 번역을 두면 옛 값이 살아남고 다시 저장된다. 저장된 값은 한 번
  *    옮기고(데이터 이관), 코드는 새 어휘만 안다 — 다만 무엇으로 옮겨야 하는지는 오류 문장이 말한다.
@@ -67,7 +67,7 @@ test('묻는 자리도 있다 — 화면·검사는 오류를 내지 않고 판
 /*
  * ── 옛 어휘가 코드로 되돌아오지 않게 (계획서 §6 의 검사) ────────────────────
  * ADR-0034 의 `local-declarations.test.ts` 가 `site*` 에 대해 하는 것과 같은 방식이다. 개명은 저장값·타입·
- * 화면에 걸쳐 있어서, 한 곳만 되돌아와도 그 자리가 조용히 다르게 재기동한다.
+ * 화면에 걸쳐 있어서, 한 곳만 되돌아와도 그 자리가 알리지 않고 다르게 재기동한다.
  */
 const OLD_TOKENS = [/\brealityMode\b/, /\bRealityMode\b/, /'sim-world'/, /'sim-experiment'/, /DEFAULT_REALITY_MODE/]
 
@@ -106,6 +106,6 @@ test('기본값 상수가 없다 — 미선언을 우리가 고르지 않는다'
     .split('\n')
     .filter(line => !/^\s*(\*|\/\/|\/\*)/.test(line))
     .join('\n')
-  assert.equal(/DEFAULT_RESTART_POLICY/.test(code), false, '기본값 상수가 되살아나면 미선언이 다시 조용해진다')
+  assert.equal(/DEFAULT_RESTART_POLICY/.test(code), false, '기본값 상수가 되살아나면 미선언이 다시 들어온 것이 없어진다')
   assert.match(code, /readRestartPolicy\(/, '읽는 자리는 엄격한 리더를 지난다')
 })

package/test/resync-origin-site.test.ts

@@ -35,14 +35,14 @@ test('기억이 없으면 그렇게 말한다 — 첫 사이트로 때우지 않
 test('기억한 사이트가 사라졌으면 다른 사이트로 덮지 않는다', () => {
   const { site, reason } = pickOriginSite(sites, { siteId: 'plant-9' })
   assert.equal(site, undefined)
-  assert.equal(reason, 'site-gone', '다른 현장의 구조를 이 트윈에 덮는 것은 조용히 틀린 공장이 된다')
+  assert.equal(reason, 'site-gone', '다른 현장의 구조를 이 트윈에 덮는 것은 오류 없이 틀린 공장이 된다')
 })
 
 test('빈 문자열은 기억이 아니다', () => {
   assert.equal(pickOriginSite(sites, { siteId: '  ' }).reason, 'no-remembered-site')
 })
 
-/* 배선이 사라지면 조용히 예전으로 돌아간다 — 소스 모양으로 못 박는다(리졸버는 DB·어댑터를 물고 있다). */
+/* 배선이 사라지면 알리지 않고 예전으로 돌아간다 — 소스 모양으로 못 박는다(리졸버는 DB·어댑터를 물고 있다). */
 test('다시 읽기는 인스턴스 정체로 견주고, 가져오기는 사이트 정체를 남긴다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/service/reference/reference-resolver.ts', import.meta.url)), 'utf-8')
   /* 옛 비교식은 **설명문에 남아 있어야 한다**(왜 고쳤는지가 사라지면 되돌아간다) — 그래서 코드 줄만 본다. */
@@ -60,7 +60,7 @@ test('다시 읽기는 인스턴스 정체로 견주고, 가져오기는 사이
 /*
  * ── 다시 읽기가 **현장 소속**을 지킨다 (2026-08-18 실측) ─────────────────────
  * 한 현장에 합쳐 둔 EMS 트윈 여덟을 재동기했더니 각자 공간으로 흩어졌다 — 템플릿이 낸 기본 공간으로
- * 돌아갔기 때문이다. 조용하다: 오류도 경고도 없고, 트윈은 멀쩡히 돌아간다. 그런데 그 순간 **그 현장의
+ * 돌아갔기 때문이다. 들어온 것이 없다: 오류도 경고도 없고, 트윈은 멀쩡히 돌아간다. 그런데 그 순간 **그 현장의
  * 값(요금·통화)을 함께 잃는다** — 현장 겹은 소속으로 얹히기 때문이다.
  *
  * 원인은 origin 이 「어느 현장에 합쳤나」를 기억하지 않은 것이다(구조만 기억했다).

package/test/revision-axis.test.ts

@@ -17,7 +17,7 @@
  * ── 왜 알려 주어야 하나 ─────────────────────────────────────────────────────
  * 커널의 계약이 그 이유를 적어 두었다(`resumeRevision`): 「저널이 비어 있지 않은데 0부터 다시 세면 같은
  * 트윈에 같은 리비전이 둘 생기고, 재생 순서가 뒤섞이며, 시간여행이 엉뚱한 시점을 답한다 — 오류는 안 난다.」
- * 조용히 깨지는 종류이므로 시험이 지킨다.
+ * 알리지 않고 깨지는 종류이므로 시험이 지킨다.
  *
  * ── 이 시험이 무엇을 재는가 ─────────────────────────────────────────────────
  * DB 도 커널도 띄우지 않는다. 이 규율은 **어느 경로가 무엇을 부르나**에 있고 그것은 소스에서 확인된다.
@@ -33,7 +33,7 @@ const src = readFileSync(ENGINE, 'utf8')
 /**
  * 그 함수 본문만 — 다른 경로의 호출이 섞여 판정이 흐려지지 않게.
  *
- * 끝은 **다음 멤버 선언**으로 자른다. 글자 수로 자르면 주석이 늘어난 날 조용히 짧아져서, 있는 것을
+ * 끝은 **다음 멤버 선언**으로 자른다. 글자 수로 자르면 주석이 늘어난 날 알리지 않고 짧아져서, 있는 것을
  * 없다고 말한다(거짓 빨강을 내는 가드는 없는 것보다 나쁘다).
  */
 function bodyOf(signature: string): string {
@@ -49,8 +49,14 @@ function bodyOf(signature: string): string {
 
 test('미러를 세우는 경로도 커널에 저널 머리를 알려 준다', () => {
   const body = bodyOf('static startLive(')
-  /* 저널 머리를 읽는다 — 이 조회는 예전부터 있었다(inst.revision 시드용). */
-  assert.match(body, /order: \{ revision: 'DESC' \}/, '저널 머리를 읽어야 한다')
+  /*
+   * 저널 머리를 읽는다 — 이 조회는 예전부터 있었다(inst.revision 시드용).
+   *
+   * 2026-08-28: 모양을 `findOne(order: revision DESC)` 에서 `MAX(e.revision)` 으로 바꿨다. 앞의 것은
+   * 관계로 물어 두 단계 질의가 되고 안쪽에 상한이 없어 그 트윈의 저널을 전부 만든 뒤 한 줄을 고른다.
+   * **묻는 것은 같다** — 저널 머리다. 그래서 이 단정은 「머리를 읽는가」로 남고 모양만 따라간다.
+   */
+  assert.match(body, /select\('MAX\(e\.revision\)'/, '저널 머리를 읽어야 한다')
   /* 그리고 **커널에도** 알려 준다 — 이 한 줄이 없어서 두 수가 갈렸다. */
   assert.match(body, /resumeRevision\(head\)/, '커널에도 그 번호를 알려 준다')
 })
@@ -72,7 +78,7 @@ test('저널이 비어 있으면 알려 주지 않는다 — 새 트윈은 0 부
 test('뒤로 되돌리려는 거절을 삼키지 않는다', () => {
   /*
    * 조회가 비동기라 그 사이에 이벤트가 들어와 있을 수 있다. 그때 커널은 뒤로 가기를 거절한다(겹치는
-   * 번호를 막는 그 판정이다). 그 거절을 조용히 버리면 「왜 두 수가 아직 다르지」를 답할 계기가 없다.
+   * 번호를 막는 그 판정이다). 그 거절을 알리지 않고 버리면 「왜 두 수가 아직 다르지」를 답할 계기가 없다.
    */
   const body = bodyOf('static startLive(')
   assert.match(body, /catch \(err[^)]*\)[\s\S]{0,200}twinWarn/, '거절을 로그에 남긴다')
@@ -81,7 +87,7 @@ test('뒤로 되돌리려는 거절을 삼키지 않는다', () => {
 
 test('체크포인트는 두 수를 나란히 적는다 — 그 사실 자체는 옳다', () => {
   /*
-   * 바깥은 저널 줄 번호(이어 쓸 자리), 안쪽은 커널이 접은 봉투 수다. **둘을 하나로 합치지 않는다** —
+   * 바깥은 저널 줄 번호(이어 쓸 자리), 안쪽은 커널이 계산한 봉투 수다. **둘을 하나로 합치지 않는다** —
    * 합치면 「어디까지 적었나」와 「어디까지 반영했나」를 구별할 수 없고, 그 구별이 미러의 정직성이다.
    * 두 경로가 대칭이면 값이 같아지지만, **자리는 둘이어야 한다.**
    */
@@ -89,7 +95,7 @@ test('체크포인트는 두 수를 나란히 적는다 — 그 사실 자체는
   assert.ok(at > 0, 'persistSnapshot 이 있어야 한다')
   /*
    * 창을 넓혀 왔다 — 이 함수 앞쪽에 「빈 상태로 좋은 스냅샷을 덮지 않는다」 가드가 들어오고(§
-   * `checkpoint-refuses-empty`), 뒤쪽에 「이어 접을 씨앗을 함께 적는다」가 들어왔다(§
+   * `checkpoint-refuses-empty`), 뒤쪽에 「이어 계산할 씨앗을 함께 적는다」가 들어왔다(§
    * `mirror-resumes-from-checkpoint`). 검사하는 **사실은 그대로**다.
    *
    * 그리고 **줄 모양이 아니라 두 자리를 검사한다**: 예전에는 `{ revision, state` 라는 한 줄 모양을
@@ -100,5 +106,5 @@ test('체크포인트는 두 수를 나란히 적는다 — 그 사실 자체는
   assert.match(body, /inst\.revision \?\? state\.revision/, '바깥은 저널 줄 번호를 먼저 쓴다')
   const call = body.slice(body.indexOf('setInCache'))
   assert.match(call, /revision/, '저널 줄 번호를 싣는다')
-  assert.match(call, /state/, '커널이 접은 상태를 함께 싣는다 — 두 자리를 하나로 합치지 않는다')
+  assert.match(call, /state/, '커널이 계산한 상태를 함께 싣는다 — 두 자리를 하나로 합치지 않는다')
 })

package/test/runtime-key.test.ts

@@ -5,7 +5,7 @@
  * 이름을 그대로 id 로 쓰므로(`sap-ewm-1710`) 두 테넌트가 같은 벤더 시스템에 연결하면 같은 id 가 된다 —
  * 그때 남의 커널에 이벤트가 적용되거나, 웜스타트 씨앗이 남의 스냅샷이 됐다.
  *
- * 이 테스트가 지키는 것은 **키가 모호해지지 않는 것** 하나다. 모호한 키는 조용히 틀린다.
+ * 이 테스트가 지키는 것은 **키가 모호해지지 않는 것** 하나다. 모호한 키는 오류 없이 틀린 값을 낸다.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
@@ -39,8 +39,8 @@ test('인스턴스 id 안의 구분자를 보존한다 — 첫 구분자에서
   assert.equal(instanceId, weird)
 })
 
-test('도메인 id 에 구분자가 있으면 오류를 낸다 — 조용히 모호한 키를 만들지 않는다', () => {
-  /* 조용히 만들면 그게 곧 이 결함의 재발이다(어느 테넌트인지 알 수 없는 키). */
+test('도메인 id 에 구분자가 있으면 오류를 낸다 — 알리지 않고 모호한 키를 만들지 않는다', () => {
+  /* 알리지 않고 만들면 그게 곧 이 결함의 재발이다(어느 테넌트인지 알 수 없는 키). */
   assert.throws(() => runtimeKey(`a${RUNTIME_KEY_SEP}b`, 'x'), /ambiguous/)
 })
 

package/test/snapshot-freshness.test.ts

@@ -1,8 +1,8 @@
 /*
  * 영속 스냅샷이 **사실을 이기지 않는다** — 쓸 수 있는 조건을 못 박는다.
  *
- * 멈춘 트윈을 조회할 때마다 저널을 전량 접고 있었다(23,731건짜리 트윈에서 4.6초). 스냅샷은 같은
- * 폴드의 결과이므로 그 뒤로 아무 일도 없었다면 다시 접어 봐야 같은 값이다 — 그래서 쓴다.
+ * 멈춘 트윈을 조회할 때마다 저널을 전량 계산하고 있었다(23,731건짜리 트윈에서 4.6초). 스냅샷은 같은
+ * 폴드의 결과이므로 그 뒤로 아무 일도 없었다면 다시 계산해 봐야 같은 값이다 — 그래서 쓴다.
  *
  * 위험은 하나다: **낡은 스냅샷을 "지금" 이라고 내는 것.** 그래서 쓰는 조건을 좁게 잡았고, 그 조건을
  * 여기서 고정한다. 엔진 본체는 DB 를 물고 있어 부를 수 없으므로 판정식만 떼어 시험한다 —
@@ -22,7 +22,7 @@ const usable = (
 const TIP = { revision: 23731, structureRev: 2 }
 const FRESH = { revision: 23731, structureRev: 2, state: { locations: [] } }
 
-test('끝에 있고 구조도 같으면 쓴다 — 다시 접어도 같은 값이다', () => {
+test('끝에 있고 구조도 같으면 쓴다 — 다시 계산해도 같은 값이다', () => {
   assert.equal(usable(FRESH, TIP, true), true)
 })
 
@@ -46,7 +46,7 @@ test('구조가 양쪽 다 없으면 그것은 같은 것이다 — 없는 것
   assert.equal(usable({ revision: 5, state: {} }, { revision: 5, structureRev: null }, true), true)
 })
 
-test('시간여행에는 쓰지 않는다 — 그 시점까지 접어야 한다', () => {
+test('시간여행에는 쓰지 않는다 — 그 시점까지 계산해야 한다', () => {
   assert.equal(usable(FRESH, TIP, false), false)
 })
 

package/test/source-outcome-audit.test.ts

@@ -2,7 +2,7 @@
  * **허락과 일어남 사이를 같은 행에 닫는다** — ADR-0029 §1 결정 C (2026-08-19).
  *
  * ── 무엇이 열려 있었나 ──────────────────────────────────────────────────────
- * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다: 어댑터가 조용히 실패하면 원장에는 승인만 남는다.
+ * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다: 어댑터가 오류 없이 실패하면 원장에는 승인만 남는다.
  * 그리고 구동 문(`controlTwinSource`)은 감사를 **아예 남기지 않았다** — 자극을 바꾸고 배속을 올리는 것은
  * 그 트윈의 사실을 바꾸는 행위인데, 나중에 「무엇이 이 공장을 흔들었나」에 답할 수 없었다.
  *

package/test/space-integrity.test.ts

@@ -217,7 +217,7 @@ test('정지한 트윈은 세지 않는다 — 확인하지 않은 것을 정합
   assert.equal(f.find(x => x.code === 'twin-unhandled-vocabulary'), undefined)
 })
 
-test('빈 배열은 결함이 아니다 — 받은 것이 없으면 조용하다', () => {
+test('빈 배열은 결함이 아니다 — 받은 것이 없으면 들어온 것이 없다', () => {
   const f = checkSpaceIntegrity({ ...SOUND, instances: [{ ...SOUND.instances[0], unhandled: [] }] })
   assert.equal(f.find(x => x.code === 'twin-unhandled-vocabulary'), undefined)
 })

package/test/space-representation.test.ts

@@ -0,0 +1,66 @@
+/*
+ * ★ 표현을 묶고 가른다 — 목록에 나올 것과 다른 표현에서 열리는 것.
+ *
+ * ── 왜 (2026-08-27 · 사용자 지시, UX 레인 요청) ─────────────────────────────
+ * 「각 표현이 많아지게 되면 관리가 어려우니, 그루핑과 정렬 기능도 필요하다.」
+ * 「표현 인덱스에 포함될 표현과 팝업 같은 파생 표현이 구분될 수 있어야 한다.」
+ *
+ * 칸 둘을 더한다.
+ *
+ *   group   자유 문자열. 묶는 축이 현장마다 다르다(건물별·용도별·층별)
+ *   role    index(기본) · derived. 닫힌 목록이다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { REPRESENTATION_ROLES } from '../server/service/twin-space/representation-role.js'
+
+const dir = (...p: string[]) => join(import.meta.dirname, '..', 'server', 'service', 'twin-space', ...p)
+const entity = readFileSync(dir('twin-space-representation.ts'), 'utf8')
+const resolver = readFileSync(dir('twin-space-resolver.ts'), 'utf8')
+
+test('★ 묶는 이름은 자유 문자열이다 — 묶는 축이 현장마다 다르다', () => {
+  assert.match(entity, /group\?: string/, 'group 칸이 있어야 한다')
+  /* 고정 목록으로 두면 현장마다 맞지 않는다 — 값을 검사하지 않는다. */
+  assert.doesNotMatch(resolver, /GROUPS as readonly|REPRESENTATION_GROUPS/, '묶는 이름을 목록으로 닫지 않는다')
+})
+
+test('★ 그룹 자체의 순서는 칸으로 두지 않는다 — 그 그룹의 최소 seq 가 그 순서다', () => {
+  /* 칸을 두면 그룹 이름을 바꿀 때 두 곳을 맞춰야 하고, 어긋나면 목록 순서가 오류 없이 달라진다. */
+  assert.doesNotMatch(entity, /groupSeq|groupOrder/, '그룹 순서 칸을 만들지 않는다')
+})
+
+test('★ role 은 닫힌 목록이고, 모르는 값은 저장하지 않는다', () => {
+  assert.deepEqual([...REPRESENTATION_ROLES], ['index', 'derived'])
+  /*
+   * 모르는 값을 그냥 저장하면 화면이 그것을 어느 쪽으로도 그리지 못하고, 그 표현이 목록에서 알리지 않고
+   * 사라진다. 저장하는 자리에서 거절한다.
+   */
+  assert.match(resolver, /REPRESENTATION_ROLES as readonly string\[\]\)\.includes\(role\)/, '닫힌 목록으로 검사한다')
+  assert.match(resolver, /unknown representation role/, '거절 사유를 말한다')
+})
+
+test('★ 비어 있으면 index 다 — 흔한 쪽을 기본으로 둔다', () => {
+  assert.match(entity, /role\?: string/, 'role 은 선택 칸이다')
+  assert.match(entity, /default when absent/, '비어 있을 때의 뜻이 설명에 있어야 한다')
+  /* 공백만 있는 값은 「없음」과 같다 — 그것을 값으로 저장하면 검사를 지나며 뜻이 없는 값이 남는다. */
+  assert.match(resolver, /String\(rep\.role\)\.trim\(\) === ''/, '공백만 있는 값은 비운다')
+  assert.match(resolver, /String\(rep\.group\)\.trim\(\) === ''/, '묶는 이름도 같다')
+})
+
+test('★ isPrimary 에 얹지 않는다 — 다른 질문에 답하는 칸이다', () => {
+  /*
+   * `isPrimary` 는 「현장 현황에 나올 하나」를 정한다. `role` 은 「목록에 나오나」를 정한다. 한 칸이
+   * 두 질문에 답하면 한쪽을 고칠 때 다른 쪽이 오류 없이 바뀐다.
+   */
+  assert.match(entity, /isPrimary\?: boolean/, 'isPrimary 는 그대로 있어야 한다')
+  assert.match(entity, /Kept separate from isPrimary/, '왜 따로 두는지 설명에 있어야 한다')
+})
+
+test('★ 조회가 두 값을 실어 보낸다 — 화면이 묶을 수 있어야 한다', () => {
+  assert.match(resolver, /group: rep\.group, role: rep\.role/, '표현 목록에 두 값을 싣는다')
+  assert.match(resolver, /order: \{ group: 'ASC', seq: 'ASC' \}/, '묶은 이름 다음에 순서로 정렬한다')
+  /* 빈 값이 앞에 오는지 뒤에 오는지는 드라이버마다 다르다 — 그 순서에 기대지 않는다. */
+  assert.match(resolver, /드라이버마다\s*\n?\s*\*?\s*다르므로/, '그 순서에 기대지 않는다는 것을 적어 둔다')
+})

package/test/space-scope-includes-stopped.test.ts

@@ -0,0 +1,55 @@
+/*
+ * ★ 현장으로 물으면 멈춘 트윈의 기록도 나온다 — 저널은 기록이고, 지금 도는지는 다른 축이다.
+ *
+ * ── 무엇이 났나 (2026-08-28 실측) ───────────────────────────────────────────
+ * 대상 해소에 `running` 조건이 있었다. 그래서 현장으로 물으면 멈춘 트윈이 대상에서 빠지고, 화면은
+ * 「기록이 없습니다」라고 말했다 — 저널에는 있는데.
+ *
+ *   twinEventList(instanceId: "ems-plant-1")      1,792건
+ *   twinEventList(spaceId:    "ems-plant-1-site")     0건   ← 같은 트윈 · 같은 도메인
+ *
+ * 규모로 보면 예외가 아니라 기본값이었다: 등록된 트윈 30개 중 도는 것 2개, 멈춘 것 28개.
+ *
+ * ── 왜 지웠나 ──────────────────────────────────────────────────────────────
+ * 옛 주석이 대는 이유(「벤치 사본은 사용자가 보는 현장이 아니다」)는 벤치 제외만 설명한다. `running` 에는
+ * 근거가 적혀 있지 않았다. 그리고 바로 다음 줄이 반대 원칙을 적어 두었다 — 「정지·비등록이어도 저널은
+ * 남아 있을 수 있다」. 그 원칙이 현장 경로에만 적용되지 않고 있었다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const KPI = join(import.meta.dirname, '..', 'server', 'engine', 'kpi-query.ts')
+const src = readFileSync(KPI, 'utf8')
+
+/** 대상을 고르는 그 한 줄만 떼어 본다. */
+const targetLine = (() => {
+  const from = src.indexOf('async function resolveTargets')
+  const body = src.slice(from, from + 1200)
+  const m = /: list\.filter\(\(x: any\) => [^\n]+\)/.exec(body)
+  return m?.[0] ?? ''
+})()
+
+test('★ 현장 경로가 「지금 도는가」로 걸러내지 않는다', () => {
+  assert.ok(targetLine, '대상을 고르는 줄을 찾아야 한다')
+  assert.doesNotMatch(targetLine, /running/, '멈춘 트윈을 현장에서 빼면 화면이 거짓 「없다」를 낸다')
+})
+
+test('벤치 사본은 계속 뺀다 — 그 제외에는 근거가 있다', () => {
+  /* 부하 시험용 사본은 사용자가 보는 현장이 아니다. 이 제외는 지우지 않는다. */
+  assert.match(targetLine, /purpose !== 'bench'/)
+})
+
+test('현장과 트윈 두 경로가 같은 원칙을 쓴다 — 저널은 기록이다', () => {
+  /* 트윈을 지정한 경로는 처음부터 「정지·비등록이어도 저널은 남아 있을 수 있다」였다. */
+  assert.match(src, /정지·비등록\)? ?지정된 트윈은 그대로 조회한다|정지·비등록/)
+  /* 왜 지웠는지가 코드에 남아 있어야 한다 — 다음 사람이 성능을 이유로 되넣지 않게. */
+  assert.match(src, /「지금 도는가」로 걸러내지 않는다/)
+  assert.match(src, /1,792건/, '무엇을 재서 알았는지 적혀 있어야 한다')
+})
+
+test('★ 「지금 도는 것만」이 필요하면 이름 있는 축으로 받는다 — 여기 숨기지 않는다', () => {
+  /* 한 칸에 두 물음을 담으면 어느 화면이 무엇을 보는지 아무도 모른다. */
+  assert.match(src, /\*\*이름 있는 축\*\*으로 받는다/)
+})

package/test/spec-coverage.test.ts

@@ -32,7 +32,7 @@ test('전부 선언되면 절대 예측 시도 가능 — 단 정확도는 별
   assert.equal(r!.varyingDurations, 2)
 })
 
-test('섞이면 partial — 한쪽만 접지된 사실을 감추지 않는다', () => {
+test('섞이면 partial — 한쪽만 계산하지된 사실을 감추지 않는다', () => {
   const r = classifySpecCoverage({
     operations: [
       { kind: 'cut', duration: 'declared' },

package/test/standard-coverage.test.ts

@@ -26,6 +26,7 @@ const req = createRequire(import.meta.url)
 const { standardsForKind } = req('../dist-server/service/twin-model/standard-coverage.js')
 const { iec61850Coverage } = req('../dist-server/service/twin-model/iec61850-coverage.js')
 const { epcisCoverage } = req('../dist-server/service/twin-model/epcis-coverage.js')
+const { isa95Coverage } = req('../dist-server/service/twin-model/isa95-coverage.js')
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
@@ -75,7 +76,7 @@ test('개폐·발전·저장이 세 층 모두 올라갔다 — 값이 먼저,
   assert.equal(iec.totals.behavior, 5, '다섯 논리 노드가 모두 실제로 돈다')
 })
 
-test('커널 축이 사라지면 구조가 없는 것으로 떨어진다 — 오타·개명이 조용히 통과하지 않게', () => {
+test('커널 축이 사라지면 구조가 없는 것으로 떨어진다 — 오타·개명이 알리지 않고 통과하지 않게', () => {
   const iec = iec61850Coverage(['equipment']) // demandWindows 축이 없는 세상
   const mmxu = iec.concepts.find(c => c.std === 'MMXU')!
   assert.equal(mmxu.structure, 'none')
@@ -104,3 +105,44 @@ test('계측은 EPCIS 센서 필드로 오지 않는다 — 그 사실을 표가
   assert.equal(sensor.behavior, 'none')
   assert.ok(sensor.note, '에너지가 다른 층으로 들어온다는 사실을 근거로 적는다')
 })
+
+test('★ 자기 축이 없는 개념은 **어디에 속하는지** 말한다 — 「어디에도 없다」로 읽히지 않게', () => {
+  /*
+   * ── 사용자 지적 (2026-08-24) ──────────────────────────────────────────────
+   * 화면이 그런 줄을 「개념 축이 없습니다」로만 냈다. 자재 로트·자원 속성·로케이션 관측 기록이 그렇게
+   * 보였는데, 셋 다 **어디엔가 속해 있다** — 로트는 물품 목록이고, 속성은 설비·사람·자산 안에 붙고,
+   * 관측은 로케이션에 붙는다. 「축이 없다」는 사실이지만 사용자에게는 **없는 것**으로 읽힌다.
+   *
+   * 그래서 `shownOn` 의 뜻을 고쳤다 — 「어디서 보이나」가 아니라 **「어디에 속하나」**다. 화면에
+   * 그려지는지는 `surface` 가 따로 답하고, 둘은 다른 물음이다.
+   *
+   * (그리고 화면의 「해당 축 항목에 표시됩니다」 문장은 걷었다 — 칩이 이미 갈 곳을 보인다.)
+   */
+  const AXES = [
+    'items', 'locations', 'equipment', 'persons', 'assets', 'tasks', 'orders', 'operations', 'recipes',
+    'testSpecifications', 'materialDefinitions', 'materialClasses', 'personnelClasses', 'equipmentClasses',
+    'assetClasses', 'productionSpec', 'demandWindows', 'meters'
+  ]
+  const tables: [string, { concepts: any[] }][] = [
+    ['ISA-95', isa95Coverage(AXES)],
+    ['EPCIS', epcisCoverage(AXES)],
+    ['IEC 61850', iec61850Coverage(AXES)]
+  ]
+
+  /*
+   * 규칙: **세 층 중 하나라도 있는 개념은 어디에 속하는지 말해야 한다.** 셋 다 없으면 진짜 빈칸이고,
+   * 그때만 「축이 없다」가 정직한 답이다.
+   */
+  const mute: string[] = []
+  for (const [name, table] of tables) {
+    for (const c of table.concepts) {
+      const lives = c.structure !== 'none' || c.behavior !== 'none' || c.surface !== 'none'
+      if (lives && !c.axis && !c.shownOn?.length) mute.push(`${name}/${c.std}`)
+    }
+  }
+  assert.deepEqual(mute, [], `있는데 어디에 속하는지 말하지 않는 줄 — 「어디에도 없다」로 읽힌다:\n${mute.join('\n')}`)
+
+  /* 빈 비교로 통과하지 않게 — 실제로 그런 줄이 여럿 있다(자재 로트·서브로트·속성·관측·시험 결과). */
+  const attached = tables.flatMap(([, t]) => t.concepts).filter(c => !c.axis && c.shownOn?.length)
+  assert.ok(attached.length >= 4, `속해 있다고 말하는 줄이 실제로 있어야 한다 (실제 ${attached.length})`)
+})

package/test/status-tally.test.ts

@@ -33,7 +33,7 @@ test('낱말은 커널의 것 그대로 — 묶거나 고쳐 부르지 않는다
   assert.deepEqual(
     r.statusCounts?.map(s => s.status).sort(),
     ['assigned', 'created'],
-    '「대기」처럼 앱의 낱말로 바꾸면 커널이 늘린 낱말을 화면이 조용히 잘못 부른다'
+    '「대기」처럼 앱의 낱말로 바꾸면 커널이 늘린 낱말을 화면이 알리지 않고 잘못 부른다'
   )
 })