@things-factory/headless-twin 10.0.15 → 10.0.18

package/test/subject-read-model.test.ts

@@ -0,0 +1,175 @@
+/*
+ * ★ 조회용 파생 표의 규율 — 앞으로만 채우고, 담지 않은 구간을 말한다.
+ *
+ * ── 왜 이 표를 만들었나 (2026-08-27 실측) ───────────────────────────────────
+ * 360 화면의 「이 대상의 이력」이 64초다. 「무엇으로 걸러 시각순으로 정렬해 앞에서 30개」라는 모양에
+ * 맞는 목차가 저널에 없고, 얹어도 풀리지 않는다.
+ *
+ *   여러 값으로 거르면(IN) 정렬 때문에 목차를 못 쓴다 — 실측한 질의 계획
+ *   축이 늘 때마다 저널의 목차가 늘어난다 — 360 의 축 넷이면 13개
+ *   품목과 로트가 한 문자열에 붙어 있어 품목만으로는 찾을 수 없다 — 정확일치가 0건
+ *
+ * ── 이 테스트가 무엇을 지키나 ───────────────────────────────────────────────
+ * DB 를 띄우지 않는다. 지켜야 할 것은 **규율**이고 그것은 순수하게 확인할 수 있다 — 목차가 조회 모양과
+ * 같은 순서인가, 소급 채우기를 하지 않는가, 담지 않은 구간을 말하는가, 저널이 먼저인가.
+ *
+ * 설계: `operato-twin/design/plans/read-models.md`
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const dir = (...p: string[]) => join(import.meta.dirname, '..', 'server', ...p)
+const entity = readFileSync(dir('service', 'twin-subject', 'twin-subject-event.ts'), 'utf8')
+const writer = readFileSync(dir('service', 'twin-subject', 'twin-subject-writer.ts'), 'utf8')
+const query = readFileSync(dir('service', 'twin-subject', 'twin-subject-query.ts'), 'utf8')
+const resolver = readFileSync(dir('service', 'twin-subject', 'item-resolver.ts'), 'utf8')
+const engine = readFileSync(dir('engine', 'twin-engine.ts'), 'utf8')
+
+test('★ 목차 순서가 조회 모양과 같다 — 이 순서가 이 표의 존재 이유다', () => {
+  /*
+   * 「이 트윈의 이 대상의 것을 최신순으로 30개」가 빠르려면 목차가 거르는 값 다음에 시각이어야 한다.
+   * 순서가 바뀌면 다시 정렬하게 되고, 그것이 저널에서 64초가 된 바로 그 원인이다.
+   */
+  assert.match(
+    entity,
+    /ix_twin_subject_event_0'[\s\S]{0,160}?\[e\.domain, e\.instanceId, e\.subjectKind, e\.subjectId, e\.eventTime\]/,
+    '(도메인, 트윈, 종류, 식별자, 시각) 순서여야 한다'
+  )
+  /* 보관 상한을 지우는 축도 시각이 마지막이어야 한다(경계를 시각으로 찾으므로). */
+  assert.match(
+    entity,
+    /ix_twin_subject_event_1'[\s\S]{0,160}?\[e\.domain, e\.instanceId, e\.eventTime\]/,
+    '(도메인, 트윈, 시각) 목차가 있어야 한다'
+  )
+})
+
+test('★ 시각 컬럼에 드라이버 방언을 적지 않는다 — datetime 은 Postgres 가 거절한다', () => {
+  const at = entity.indexOf('eventTime: Date')
+  assert.ok(at > 0, 'eventTime 이 있어야 한다')
+  const decl = entity.slice(Math.max(0, at - 400), at)
+  assert.doesNotMatch(decl, /type: 'datetime'/, 'sqlite·MySQL 의 이름을 적지 않는다')
+  assert.doesNotMatch(decl, /type: 'timestamp'/, 'Postgres 의 이름도 적지 않는다')
+})
+
+test('★ 저널이 먼저다 — 이 표에 적다가 실패해도 저널 쓰기를 되돌리지 않는다', () => {
+  /* 사실의 원본은 저널이고 이 표는 다시 만들 수 있다. 반대로 두면 조회를 빠르게 하려고 만든 표가
+     사실을 잃는 원인이 된다. */
+  assert.match(writer, /catch \(err: any\)[\s\S]{0,200}?noteFailure/, '실패를 잡아 세어야 한다')
+  assert.match(writer, /return 0\s*\n\s*\}/, '실패해도 던지지 않는다')
+})
+
+test('★ 알리지 않고 비지 않는다 — 적지 못한 줄 수를 조회가 함께 낸다', () => {
+  /* 알리지 않고 비면 화면이 「그 대상에는 사건이 없다」고 말하게 된다. 그것이 이 부류에서 가장 나쁜 결함이다. */
+  assert.match(writer, /export function subjectWriteFailures/, '적지 못한 수를 물을 수 있어야 한다')
+  assert.match(query, /writeFailures: subjectWriteFailures\(/, '조회가 그 수를 실어 보낸다')
+  assert.match(query, /writeFailures: number/, '응답에 그 칸이 있어야 한다')
+})
+
+test('★ 담지 않은 구간을 말한다 — 앞으로만 채우므로 그 앞은 「없다」가 아니다', () => {
+  assert.match(query, /coveredFrom\?: Date/, '경계를 낼 칸이 있어야 한다')
+  assert.match(query, /orderBy\('s\.eventTime', 'ASC'\)[\s\S]{0,120}?limit\(1\)/, '가장 오래된 줄 하나로 구한다')
+  /* 저장하지 않고 조회할 때 구한다 — 저장한 값은 실제 자료와 어긋날 수 있다. */
+  assert.doesNotMatch(entity, /coveredFrom/, '경계를 표에 저장하지 않는다')
+})
+
+test('★ 종류가 닫힌 목록이고, 모르는 값은 빈 목록이 아니라 오류다', () => {
+  /* 빈 목록으로 답하면 오타가 「그 대상에는 사건이 없다」로 보인다. */
+  assert.match(query, /SUBJECT_KINDS as readonly string\[\]\)\.includes\(kind\)/, '닫힌 목록으로 검사한다')
+  assert.match(query, /throw new Error\(`unknown subjectKind/, '모르는 종류는 오류를 낸다')
+  assert.match(query, /subjectId is required/, '빈 식별자로 트윈 전체를 읽지 않는다')
+})
+
+test('★ 페이지를 시각으로 넘긴다 — 머리에 쌓이는 목록에서 건너뛰기는 본 줄을 다시 낸다', () => {
+  assert.match(query, /eventTime < :before/, '시각 커서로 넘긴다')
+  assert.doesNotMatch(query, /\.skip\(/, '건너뛰기(offset)를 쓰지 않는다')
+})
+
+test('★ 품목은 선언과 견주어 판정한다 — 문자열을 자르지 않는다', () => {
+  /*
+   * 어느 부호가 로트를 가리키는지는 연결된 시스템마다 다르고 커널 계약이 정한 적이 없다. 한 시스템의
+   * 관습(`-lot-`)을 규칙으로 굳히면 이 코드가 그 시스템 위에 서게 된다.
+   */
+  assert.match(resolver, /resolveByDeclaration\(itemRefOf\(epc\)/, '선언과 견주어 찾는다')
+  /* 주석은 그 부호를 설명으로 쓴다 — 코드에 있는지만 본다(주석 줄을 걷어 내고 검사한다). */
+  const code = resolver
+    .split('\n')
+    .filter(l => !/^\s*(\*|\/\*|\/\/)/.test(l))
+    .join('\n')
+  assert.doesNotMatch(code, /'-lot-'|"-lot-"|split\('-'\)|indexOf\('-lot/, '문자열을 자르는 규칙을 넣지 않는다')
+  /* 사건마다 부르므로 기억해 둔다. 선언이 바뀌면 세대가 달라져 다시 판정한다. */
+  assert.match(resolver, /generation !== generation|entry\.generation !== generation/, '선언 세대를 본다')
+})
+
+test('★ 저널을 쓰는 두 문이 모두 이 표에 적는다 — 한쪽만 적으면 그만큼이 화면에서 빈다', () => {
+  const carried = engine.indexOf('static async persistCarried')
+  const batch = engine.indexOf('static async persistBatch')
+  assert.ok(carried > 0 && batch > 0, '두 문이 있어야 한다')
+  assert.match(engine.slice(carried, carried + 900), /this\.writeSubjects\(/, 'persistCarried 가 적는다')
+  assert.match(engine.slice(batch, batch + 900), /this\.writeSubjects\(/, 'persistBatch 가 적는다')
+})
+
+test('★ 소급해서 채우지 않는다 — 마이그레이션이 표만 만든다', () => {
+  const migration = readFileSync(dir('migrations', '1786500000000-CreateTwinSubjectEvents.ts'), 'utf8')
+  assert.match(migration, /createTable/, '표를 만든다')
+  assert.match(migration, /createIndex/, '목차를 만든다')
+  /* 채우는 코드가 있으면 새 조회 축마다 3,128만 줄을 다시 만드는 구조가 된다. */
+  assert.doesNotMatch(migration, /INSERT|insert\(|from twin_events|TwinEvent/i, '기존 사건을 옮기지 않는다')
+  const list = readFileSync(dir('migrations', 'index.ts'), 'utf8')
+  assert.match(list, /CreateTwinSubjectEvents1786500000000/, '마이그레이션 목록에 배선돼 있어야 한다')
+})
+
+test('★ 이 표의 보관 정리는 체크포인트 상한을 보지 않는다 — 잃을 사실이 없다', () => {
+  /*
+   * 저널의 정리는 체크포인트가 반영하지 못한 사건을 지우지 않는다(그것을 지우면 사실이 사라진다).
+   * 이 표는 사건에서 파생된 값이라 지워도 사실이 사라지지 않는다 — 그 구간의 조회가 느려질 뿐이다.
+   */
+  assert.match(writer, /export async function pruneSubjectRows/, '정리 함수가 있어야 한다')
+  assert.doesNotMatch(writer, /revision <= :upTo/, '체크포인트 상한을 보지 않는다')
+  assert.match(writer, /orderBy\('s\.eventTime', 'ASC'\)/, '경계를 시각으로 찾는다 — 목차를 쓰려면 그래야 한다')
+  /* 저널 정리와 같은 창에서 돈다 — 두 표가 같은 보관 기간을 본다. */
+  assert.match(engine, /pruneSubjectRows\(/, '저널 정리 창에서 함께 부른다')
+})
+
+test('★ 어디까지 옮겼는지 이 프로세스가 든다 — 파생 테이블의 내용으로 알아내지 않는다', () => {
+  /*
+   * 저장하지 않고 파생 테이블의 내용으로 진행 지점을 알아내려 했고 세 번 틀렸다.
+   *
+   *   ① 최대 리비전 뒤부터    실시간으로 채워진 줄의 최댓값이 곧 저널의 끝이라 옮길 구간을 다 건너뛴다
+   *   ② 최소 리비전 앞까지    1부터 적으면 최솟값이 1이 되어 구간이 0으로 접힌다
+   *   ③ 최소 시각 아래로      사건이 시각순으로 오지 않는 트윈에서 곧바로 끝난다
+   *
+   * 채워진 것은 구간이 아니라 집합이다. 어느 축으로도 하나의 경계로 말할 수 없다.
+   *
+   * 그래서 알아내려 하지 않고 든다. **테이블에 적지 않는다**(사용자 판단) — 사건이 들어올 때 파생
+   * 테이블도 같이 적히므로, 옛 사건을 옮기는 일은 새 파생 테이블을 만들 때와 계산 규칙을 고쳤을 때뿐이다.
+   * 대가는 서버가 내려가면 그 몫을 다시 읽는 것이다.
+   */
+  const backfill = readFileSync(dir('service', 'twin-subject', 'twin-subject-backfill.ts'), 'utf8')
+  assert.match(backfill, /const inFlight = new Map</, '이 프로세스가 든다')
+  assert.doesNotMatch(backfill, /TwinProjectionProgress|progressRepo/, '테이블에 적지 않는다')
+  assert.doesNotMatch(backfill, /MIN\(s\.revision\)|MAX\(s\.revision\)|MIN\(s\.eventTime\)/, '파생 테이블의 내용으로 알아내지 않는다')
+  /* 목표는 처음 부를 때 한 번 정한다 — 매번 다시 재면 새 사건이 들어와 끝나지 않는다. */
+  assert.match(backfill, /targetRevision: Number\(tip\?\.max \?\? 0\)/, '목표를 한 번 정한다')
+  /* 다 옮기면 들고 있지 않는다 — 남겨 두면 다음 호출이 옛 목표를 본다. */
+  assert.match(backfill, /if \(complete\) inFlight\.delete\(key\)/, '끝나면 버린다')
+})
+
+test('★ 목록의 순서가 같은 시각에서도 정해진다 — 페이지가 본 줄을 다시 내지 않게', () => {
+  assert.match(query, /addOrderBy\('s\.revision', 'DESC'\)/, '같은 시각은 리비전으로 가른다')
+})
+
+test('★ 선언한 엔티티를 등록한다 — 선언만 하면 테이블이 만들어지지 않는다', () => {
+  /*
+   * 파생 테이블 엔티티를 만들고 `entities` 에 넣지 않은 적이 있다. 그러면 테이블이 만들어지지 않고,
+   * 그것을 쓰는 코드가 「그런 테이블 없다」로 실패한다. 파일이 있는 것과 등록된 것은 다르다.
+   */
+  const index = readFileSync(dir('service', 'twin-subject', 'index.ts'), 'utf8')
+  assert.match(index, /entities = \[TwinSubjectEvent\]/, '이 폴더의 엔티티가 등록돼 있어야 한다')
+  const services = readFileSync(dir('service', 'index.ts'), 'utf8')
+  assert.match(services, /\.\.\.TwinSubjectEntities/, '서비스 목록에도 실려야 한다')
+  /* 마이그레이션의 테이블 이름은 TypeORM 이 만든 것과 글자 그대로 같아야 한다. */
+  const migration = readFileSync(dir('migrations', '1786500000000-CreateTwinSubjectEvents.ts'), 'utf8')
+  assert.match(migration, /const TABLE = 'twin_subject_events'/, '실제 테이블 이름을 쓴다')
+})

package/test/touched-items.test.ts

@@ -5,7 +5,7 @@
  *  ① 개체를 말한 자리를 전부 읽는다 — 관측·집약(부모/자식)·변환(입력/출력).
  *  ② 부류 수량만 말한 사건은 「모른다」다 — 그 부류의 어느 개체인지 말하지 않았다.
  *  ③ 물품을 만지지 않는다고 **선언된** 사건은 빈 범위다(작업·설비·인원·자산·오더·품질·확인·에너지).
- *  ④ 낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리지 않는다.
+ *  ④ 낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 알리지 않고 빠뜨리지 않는다.
  *
  * 「모른다」(`null`)와 「하나도 없다」(빈 집합)는 **다른 사실**이다. 앞은 전부 다시 만들게 하고 뒤는
  * 물품을 건너뛰게 한다 — 둘을 같게 두면 둘 중 하나가 반드시 틀린다.
@@ -53,7 +53,7 @@ test('물품을 만지지 않는다고 선언된 사건은 빈 범위다 — 전
   assert.equal(energy!.size, 0)
 })
 
-test('낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리지 않는다', () => {
+test('낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 알리지 않고 빠뜨리지 않는다', () => {
   assert.equal(touchedItemKeys({ eventType: 'something.new', data: { epcList: ['x'] } }), null)
   assert.equal(touchedItemKeys({ data: { epcList: ['x'] } }), null, '낱말이 없으면 판정할 수 없다')
   assert.equal(touchedItemKeys(undefined), null)

package/test/twin-audit.test.ts

@@ -63,7 +63,7 @@ test('근거는 문자열일 때만 싣는다 — 객체를 그대로 넣어 화
   assert.equal(bad.reason, undefined)
 })
 
-test('args 가 지나치게 크면 자르되 잘랐다고 알린다 — 조용히 버리지 않는다', () => {
+test('args 가 지나치게 크면 자르되 잘랐다고 알린다 — 알리지 않고 버리지 않는다', () => {
   const huge = { blob: 'x'.repeat(9000) }
   const row = buildCommandAudit({ command: { type: 't', args: huge }, ack: {}, at: AT })
   assert.equal(row.argsTruncated, true)

package/test/twin-event-keys.test.ts

@@ -140,7 +140,7 @@ test('payload 가 data 로 감싸이지 않은 모양도 받는다', () => {
   assert.equal(epcOf({ epcList: ['urn:epc:id:sgtin:1.2.3'] }), 'urn:epc:id:sgtin:1.2.3')
 })
 
-test('상한을 넘는 값은 조용히 사라지지 않는다 — 잘리되 경고가 남는다', () => {
+test('상한을 넘는 값은 오류 없이 사라지지 않는다 — 잘리되 경고가 남는다', () => {
   const long = 'urn:epc:id:sgtin:' + 'x'.repeat(400)
   const warned: string[] = []
   const orig = console.warn

package/test/twin-model-item-db.test.ts

@@ -6,7 +6,7 @@
  *
  * 여기서 지키는 것:
  *  · 어떻게 셌는지 밝힌다 — 행이면 DB 가 페이징, 문서면 서버가 통째로 읽어 잘랐다(`basis`)
- *  · 조용히 자르지 않는다 — 총 건수가 항상 함께 오고, 훑기가 상한에 닿으면 그렇다고 말한다
+ *  · 알리지 않고 자르지 않는다 — 총 건수가 항상 함께 오고, 훑기가 상한에 닿으면 그렇다고 말한다
  *  · 모르는 축은 **거절한다** — 빈 목록으로 답하면 오타 하나가 "우리 트윈엔 그게 없다" 로 굳는다
  *  · 투영이 낡아도 항목은 열린다 — 행에 없으면 문서에서 찾는다
  *  · 이어진 것은 **양방향**이고, 선언된 관계만 따른다(선언에 없는 길은 그리지 않는다)
@@ -141,7 +141,7 @@ test('비교하지 못했으면 관측은 null 이고, 답했으면 **근거를
    * 이 픽스처에는 저널이 없다(행만 있다) — 되짚을 것이 없으므로 관측은 없다. **0 이나 빈 객체로
    * 메우면 "관측했는데 아무것도 없었다" 로 읽힌다.**
    *
-   * 예전 이 검사는 "트윈이 안 돌면 관측은 null" 이었다. 지금은 멈춘 트윈도 저널을 접어 답할 수 있고,
+   * 예전 이 검사는 "트윈이 안 돌면 관측은 null" 이었다. 지금은 멈춘 트윈도 저널을 계산해 답할 수 있고,
    * 그 답이 **자기 근거를 달고 온다**(`observedBasis`). 그래서 규율을 그 자리에 맞춰 다시 적는다:
    * 답이 없으면 null, 답이 있으면 그것이 라이브인지 되짚은 것인지 말한다. 근거 없는 답은 없다.
    */
@@ -230,10 +230,10 @@ test('지도의 선이 진단이 된다 — 이어진 것뿐 아니라 **끊긴
  * ★ 관측 열이 **자기 근거를 말한다** — 라이브인지 되짚은 것인지.
  *
  * 둘은 같은 모양의 값이라, 근거가 없으면 되짚은 값을 "지금 이렇다" 로 읽는다. 그래서 근거를 실을
- * 자리가 없던 동안에는 멈춘 트윈의 저널을 아예 접지 않았다(관측 열이 통째로 `—`). 자리를 만든 뒤의
+ * 자리가 없던 동안에는 멈춘 트윈의 저널을 아예 계산하지 않았다(관측 열이 통째로 `—`). 자리를 만든 뒤의
  * 규율은 하나다: **답하면 근거를 말한다.**
  */
-test('멈춘 트윈도 저널을 접어 답하고, 그 답은 다시 계산한 값이라고 알린다', async () => {
+test('멈춘 트윈도 저널을 계산해 답하고, 그 답은 다시 계산한 값이라고 알린다', async () => {
   const { WmsKernel, EventJournal } = req('@operato/twin-kernel')
   const model = {
     spaceId: 'journal-space',
@@ -273,5 +273,5 @@ test('멈춘 트윈도 저널을 접어 답하고, 그 답은 다시 계산한
   const it = await q.twinModelItem(INST, 'equipment', 'fk-1', ctx)
   assert.ok(it?.observed, '저널이 있으면 멈춘 트윈도 마지막으로 알던 사실을 답할 수 있다')
   assert.equal(it.observedBasis, 'journal', '라이브가 아니라 되짚은 것이라고 말해야 "지금 이렇다" 로 읽히지 않는다')
-  assert.ok(it.observedRevision > 0, '몇 번째 리비전까지 접었는지 함께 말한다 — 규모의 한계도 그 수가 말한다')
+  assert.ok(it.observedRevision > 0, '몇 번째 리비전까지 계산했는지 함께 말한다 — 규모의 한계도 그 수가 말한다')
 })

package/test/twin-model-tree-db.test.ts

@@ -7,7 +7,7 @@
  *
  * 여기서 지키는 것:
  *  · 패턴을 코드가 알지 않는다 — 선언 그래프에서 자기 축으로 돌아오는 순환을 찾는다
- *  · **조용히 고르지 않는다** — 순환이 여럿이면 후보를 내고 멈춘다(방향이 뒤집힌 전개는
+ *  · **알리지 않고 고르지 않는다** — 순환이 여럿이면 후보를 내고 멈춘다(방향이 뒤집힌 전개는
  *    틀린 답이 아니라 **반대의 답**이라 화면만 보고는 구별되지 않는다)
  *  · 수량은 곱해 내려가되, **모르면 곱하지 않는다**(1 로 메우면 윗단 합계가 통째로 거짓이 된다)
  *  · 사이클을 만나면 다시 파지 않고 말한다
@@ -153,7 +153,7 @@ test('사이클은 다시 탐색하지 않고 알린다', async () => {
   await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
-test('상한에서 끊기면 끊겼다고 알린다 — 조용히 자르지 않는다', async () => {
+test('상한에서 끊기면 끊겼다고 알린다 — 알리지 않고 자르지 않는다', async () => {
   const shallow = await explode('trailer', { maxDepth: 1 })
   assert.equal(shallow.truncated.depth, true)
   assert.deepEqual(shallow.items.filter((n: any) => n.depth === 2), [], '깊이 상한 아래는 안 판다')
@@ -174,3 +174,36 @@ test('선언에 없는 자재를 참조하면 그 사실이 드러난다', async
   assert.equal(child.known, false, '선언에 없다는 사실을 함께 낸다(있는 척하지 않는다)')
   await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
+
+test('★ 선언에 없는 축을 거치면 터지지 않고 **왜 못 하는지 말한다**', async () => {
+  /*
+   * ── 실측으로 터진 것 (2026-08-24) ────────────────────────────────────────
+   * 이 전개는 **트윈 모델의 선언**을 읽는다(`axisInfo(...).path` 로 모델 안을 찾아 들어간다). 그런데
+   * 커널 카탈로그의 축 중 셋은 **선언되는 것이 아니라 일어나는 것**이다 — `orders`·`tasks`·`items`
+   * 는 사건이 만들고 끝나면 사라진다. 모델이 그 목록을 가질 수 없으므로 `path` 가 비어 있다.
+   *
+   *   Cannot read properties of undefined (reading 'split')
+   *
+   * ★ **터진 것은 요청한 축이 아니라 「거쳐 가는 축」이다.** `locations` 를 물으면 그 순환이 `tasks` 를
+   * 거치는데(작업이 `from`·`at` 으로 자리를 두 번 가리킨다) 그 `tasks` 에 경로가 없다. 그래서 요청한
+   * 축만 지켜서는 막히지 않는다 — 처음에 그렇게 고쳤다가 이 시험이 잡았다.
+   *
+   * 그리고 빈 트리로 답하면 화면이 「이어진 것이 없다」로 읽는데 그것은 거짓이다 — 작업은 자리를
+   * 가리키고 있고, 다만 이 질의가 그것을 아는 곳이 아니다.
+   */
+  const q = new TwinModelTreeQuery()
+  const ctx = { state: { domain: { id: domainId } } } as any
+
+  /* 두 홉을 지정해야 순환이 하나로 정해진다 — 안 지정하면 앞 갈래(모호함)에서 답한다. */
+  const loc = await q.twinModelTree(INSTANCE, 'locations', 'st-a', ctx, 'twin.rel.from', 'twin.rel.at')
+  assert.ok(loc, 'locations: 터지지 않는다')
+  assert.deepEqual(loc.items, [], 'locations: 펼친 것이 없다')
+  assert.equal(loc.reason, 'not-declared-in-model', 'locations: 왜 못 하는지 말한다(거쳐 갈 축이 선언에 없다)')
+
+  /* 자기참조 순환이 아예 없는 축은 그 사실을 말한다 — 이유가 다르면 낱말도 달라야 한다. */
+  for (const axis of ['orders', 'tasks', 'items']) {
+    const r = await q.twinModelTree(INSTANCE, axis, 'anything', ctx)
+    assert.ok(r, `${axis}: 터지지 않는다`)
+    assert.equal(r.reason, 'no-recursive-relation', `${axis}: 순환이 없다는 사실을 말한다`)
+  }
+})

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

@@ -75,7 +75,7 @@ test('인제스트가 원천을 각인한다 — 원천이 무엇이든 한 자
 test('원천을 모르는 재프로비전이 이미 아는 것을 지우지 않는다 — 한 번 지우면 다시 못 읽는다', async () => {
   /*
    * 이 경로는 실제로 있다 — 원천을 모르는 호출자(스크립트·복구·옛 코드)가 같은 트윈을 다시
-   * 인제스트한다. 그때 `origin` 을 덮어 비우면 그 트윈은 **조용히 다시 읽을 수 없게 된다.**
+   * 인제스트한다. 그때 `origin` 을 덮어 비우면 그 트윈은 **알리지 않고 다시 읽을 수 없게 된다.**
    * 그런 종류의 손상은 다음번에 다시 읽으려 할 때까지 아무도 모른다.
    */
   await TwinEngine.ingestMaster(domainId, master(BORN, 5), 'reset')

package/test/vocabulary-guard.test.ts

@@ -14,7 +14,7 @@ import assert from 'node:assert/strict'
 import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { retiredVocabularyIn } from '@operato/twin-kernel'
+import { retiredVocabularyIn } from '@operato/ops-contract'
 
 const ROOTS = ['server', 'client'].map(d => new URL(`../${d}`, import.meta.url).pathname)
 

package/test/warm-start-seam.test.ts

@@ -12,7 +12,7 @@
  *
  * ── 무엇을 단언하나 ────────────────────────────────────────────────────────
  * 스냅샷의 오더가 남은 데맨드(requested − fulfilled)로 커널에 서고, 이행이 끝난 오더는 서지 않고,
- * 원값이 없는 오더는 조용히 서지 않는다는 것. 숫자를 지어내지 않는다는 규칙이 이음매 끝까지 지켜지는가.
+ * 원값이 없는 오더는 알리지 않고 서지 않는다는 것. 숫자를 지어내지 않는다는 규칙이 이음매 끝까지 지켜지는가.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'

package/test/warm-start.test.ts

@@ -1,7 +1,7 @@
 /*
  * ★ 웜스타트 판정 검증 — 재기동하는 커널에 직전 관측 상태를 심을지.
  *
- * 이 판정은 **양쪽으로 조용히 틀린다**: 심어야 할 때 안 심으면 있는 재고가 0 으로 보이고
+ * 이 판정은 **양쪽으로 오류 없이 틀린 값을 낸다**: 심어야 할 때 안 심으면 있는 재고가 0 으로 보이고
  * (2026-07-31 hatiolab-wms — 저널에 입고 540·출고 94 인데 재고 화면이 비어 있었다),
  * 벤치에 심으면 용량 측정이 오염된다. 둘 다 화면에는 아무 이상이 없어 보인다.
  */
@@ -41,7 +41,7 @@ test('원값 없는 오더는 심지 않는다 — 남은 수량을 알 수 없
 
 test('뺀 오더의 수를 센다 — "주문이 없다" 와 "주문을 못 심었다" 가 같아지면 안 된다', () => {
   /*
-   * 이 숫자가 로그의 근거다. 세지 않고 조용히 빼면, 재기동 후 빈 주문 목록을 보고
+   * 이 숫자가 로그의 근거다. 세지 않고 알리지 않고 빼면, 재기동 후 빈 주문 목록을 보고
    * 사용자는 "원래 없었다" 로 읽는다. 실제로 그 화면이 오래 남아 있었다.
    */
   const mixed = {
@@ -117,7 +117,7 @@ test('벤치 판정은 상태 유무보다 먼저다 — 상태가 없어도 이
   assert.deepEqual(planWarmStart(null, 'bench', true), { action: 'skip', reason: 'bench' })
 })
 
-test('심을 상태가 없으면 조용히 넘어간다 — 처음 만든 트윈의 정상 경로다', () => {
+test('심을 상태가 없으면 알리지 않고 넘어간다 — 처음 만든 트윈의 정상 경로다', () => {
   assert.deepEqual(planWarmStart(null, undefined, true), { action: 'skip', reason: 'no-state' })
   assert.deepEqual(planWarmStart(undefined, undefined, true), { action: 'skip', reason: 'no-state' })
   assert.deepEqual(planWarmStart({ locations: [], items: [], equipment: [] }, undefined, true), { action: 'skip', reason: 'no-state' })
@@ -130,7 +130,7 @@ test('노드만 있어도 심는다 — 구조 배치가 복원되면 화면이
   assert.equal(plan.itemCount, 0)
 })
 
-test('커널이 주입을 지원하지 않으면 알린다 — 조용히 빈 채로 뜨면 안 된다', () => {
+test('커널이 주입을 지원하지 않으면 알린다 — 알리지 않고 빈 채로 뜨면 안 된다', () => {
   assert.deepEqual(planWarmStart(STATE, undefined, false), { action: 'skip', reason: 'unsupported' })
 })
 
@@ -178,7 +178,7 @@ test('확인 처리가 문자열 목록이 아니면 없는 것으로 본다 —
 /*
  * ── 겹포장 회귀 방지 (2026-08-05) ──────────────────────────────────────────
  * 체크포인트가 `{revision, state:{revision, state:{실제}}}` 로 저장돼, 꺼낸 값에 축이 하나도 없었다.
- * 판정은 "심을 것이 없다"(no-state)로 답하고 **조용히** 넘어갔다 — 저널에 수천 건이 있고 캐시도
+ * 판정은 "심을 것이 없다"(no-state)로 답하고 **알리지 않고** 넘어갔다 — 저널에 수천 건이 있고 캐시도
  * 최신인데 트윈이 빈 채로 떴다. 오류도 로그도 없어서 이 경로가 처음부터 죽어 있었다.
  */
 test('봉투로 감싸여 와도 벗겨서 심는다 — 체크포인트가 겹포장돼 복원이 죽었던 자리', () => {
@@ -283,7 +283,7 @@ test('겹포장된 체크포인트도 벗겨 읽는다 — 한 번은 반드시
   assert.equal(plan.energy, true)
 })
 
-/* 배선이 사라지면 미러는 조용히 예전으로 돌아간다 — 소스 모양으로 못 박는다(엔진은 DB 를 물고 있다). */
+/* 배선이 사라지면 미러는 알리지 않고 예전으로 돌아간다 — 소스 모양으로 못 박는다(엔진은 DB 를 물고 있다). */
 test('미러 기동이 연속성 씨앗을 심는다 — 배선이 사라지지 않게', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
   const at = src.indexOf('static startLive(')

package/test/withheld-door.test.ts

@@ -1,7 +1,7 @@
 /*
  * ★ **원본에 있는데 세우지 않은 것** — 그 사실이 스쳐 지나가지 않게.
  *
- * ── 무엇이 조용했나 (2026-08-24) ────────────────────────────────────────────
+ * ── 무엇이 아무 신호도 내지 않았나 (2026-08-24) ────────────────────────────────────────────
  * 커넥터가 원본의 사실 일부를 **일부러 받지 않는 일이 정상이다**(입자가 안 맞는다 · 받으면 상태가
  * 거짓이 된다 · 커널 어휘로 옮길 수 없다). 그때 경고를 내는데, 그 경고의 유일한 소비처가 **프로비저닝
  * 마법사**였다 — 트윈을 만드는 동안만 뜨는 화면이다.
@@ -32,7 +32,7 @@ const REASON = '아직 지시되지 않은 생산계획을 세우지 않았다
 test('★ 세우지 않은 것이 조회에 나온다 — 유입이 한 건도 없어도', () => {
   /*
    * 이 갈래가 중요하다: 원본이 말하는데 **전부** 안 받는 경우가 있고, 그때 유입은 0 이다.
-   * 유입 있는 갈래에서만 내면 바로 그 상황에서 조용해진다.
+   * 유입 있는 갈래에서만 내면 바로 그 상황에서 들어온 것이 없어진다.
    */
   const l = newIngestLedger()
   recordWithheld(l, REASON, 8, Date.parse('2026-08-24T11:19:16.000Z'))

package/test/yield-loop.test.ts

@@ -1,9 +1,9 @@
 /*
- * **한 바퀴** — 커널이 라인을 돌리고, 그 이벤트를 접어, 배운 수율이 다시 커널로 들어간다.
+ * **한 바퀴** — 커널이 라인을 돌리고, 그 이벤트를 계산해, 배운 수율이 다시 커널로 들어간다.
  *
  * ── 왜 이 시험이 필요했나 (2026-08-19) ─────────────────────────────────────
  * 층마다 시험이 있었다(커널 7 · 호스트 9). 그런데 **사슬이 이어졌는지**는 층 시험으로 알 수 없다 —
- * 이벤트 모양이 한 칸만 어긋나도 각 층은 통과하면서 전체는 조용히 상수로 돈다.
+ * 이벤트 모양이 한 칸만 어긋나도 각 층은 통과하면서 전체는 알리지 않고 상수로 돈다.
  *
  * 실 앱에서 보려고 데모 MES 트윈으로 한 바퀴를 돌리려 했는데 두 번 막혔다: ① 데모의 자극(시나리오)은
  * **시드 때만 실려서** 트윈을 재기동하면 사라진다 ② 모델에서 읽은 값으로 자극을 재구성했지만 부품 도착이
@@ -12,7 +12,7 @@
  *
  * 그래서 여기서 **DB·서버 없이** 진짜 사슬을 돌린다: 커널(MES) → `task.status` 이벤트 → 호스트의 실제
  * 폴드(`foldKpi`) → 실제 추정기(`buildYieldEstimator`) → 커널 시임. 가짜 이벤트를 손으로 만들지 않는다 —
- * 커널이 낸 것을 그대로 접는다.
+ * 커널이 낸 것을 그대로 처리한다.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
@@ -156,7 +156,7 @@ test('한 바퀴: 커널이 판정을 내고 → 폴드가 종류별로 세고
   const rows = asJournal(events)
   assert.ok(rows.length > 50, `작업 전이가 충분히 나야 한다(관측 ${rows.length})`)
 
-  /* 호스트의 **실제** 폴드로 접는다 — 시험용 계산을 따로 만들지 않는다. */
+  /* 호스트의 **실제** 폴드로 처리한다 — 시험용 계산을 따로 만들지 않는다. */
   const kpi = foldKpi(rows as any, window(rows as any), { groupBy: 'taskKind' })
   const judged = (kpi.groups?.items ?? []).filter(g => g.quality)
   assert.ok(judged.length > 0, '품질이 세어진 종류가 있어야 한다')