@things-factory/headless-twin 10.1.27 → 10.1.29

package/server/service/twin-model/external-resolver.ts

@@ -70,11 +70,22 @@ export interface ExternalIncoming {
  * 둘 다 선택이다. 이름만 대 줄 수 있는 제품과 들어오는 관계만 낼 수 있는 제품이 다 있다 — 하나만
  * 꽂아도 그만큼은 답해진다.
  */
+/** What the relation being resolved belongs to. Required — a resolver that answers without it answers for the wrong twin. */
+export interface ExternalResolveContext {
+  instanceId: string
+}
+
 export interface ExternalResolver {
   /** 계약의 `target.entity` 와 **같은 낱말**. 다르면 아무 관계에도 안 붙는다. */
   entity: string
-  /** 이 id 들이 무엇인가. */
-  resolve?(domainId: string, ids: readonly string[]): Promise<ExternalRef[]>
+  /**
+   * 이 id 들이 무엇인가 — **어느 트윈의 관계인지와 함께** 묻는다.
+   *
+   * 인스턴스를 넘기는 이유(2026-09-18): 밖의 id 는 도메인에서 유일하지 않다. 구역 id(`areaId`)는
+   * 공간 안에서만 유일하므로, 도메인만으로 찾으면 다른 공간의 같은 id 가 답이 되어 **남의 공간 이름**이
+   * 이 자리의 부모로 보인다. 부르는 쪽은 인스턴스를 알고 있다.
+   */
+  resolve?(domainId: string, ids: readonly string[], context: ExternalResolveContext): Promise<ExternalRef[]>
   /** 이 대상을 가리키는 것들. */
   incoming?(domainId: string, instanceId: string, axis: string, itemId: string): Promise<ExternalIncoming[]>
 }
@@ -120,12 +131,13 @@ export async function resolveExternal(
   entity: string,
   domainId: string,
   ids: readonly string[],
+  context: ExternalResolveContext,
   warn?: (msg: string) => void
 ): Promise<{ refs?: ExternalRef[]; unresolved?: 'no-resolver' | 'failed' }> {
   const r = resolvers.get(entity)
   if (!r?.resolve) return { unresolved: 'no-resolver' }
   try {
-    return { refs: await r.resolve(domainId, ids) }
+    return { refs: await r.resolve(domainId, ids, context) }
   } catch (e: any) {
     warn?.(`[external-resolver] '${entity}' 해소가 실패했다 — ${String(e?.message ?? e)}`)
     return { unresolved: 'failed' }

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

@@ -209,6 +209,19 @@ export class TwinLineageQuery {
       }
     } else if (!recipe) {
       conformance = { comparable: false, reason: 'no-recipe-for-material' }
+    } else if (!(madeBy.get(epc) ?? []).length) {
+      /*
+       * ── **안 본 것을 「다르다」고 하지 않는다** (2026-09-18 · :3000 화면에서 확인) ─────────
+       *
+       * 이 개체를 만든 변환이 저널에 하나도 없으면 투입을 하나도 관측하지 못한 것이다. 그런데
+       * 아래 셈은 그대로 돌아 관측을 전부 0 으로 적었고, 레시피가 요구한 자재 23 줄이 전부
+       * 「안 맞는다」가 됐다 — 화면은 「레시피와 다릅니다」를 확신에 찬 얼굴로 그렸다. 실제로는
+       * 원본이 변환을 아직 안 보냈을 뿐이다(`mes-miratek` 의 카메라 로트가 그 경우다).
+       *
+       * 이 파일의 규율이 이미 그것을 말한다 — 짐작으로 이으면 「설계와 다르다」는 거짓 진단이
+       * 되고, 그건 아무 말도 안 하는 것보다 나쁘다. 관측이 **없는** 것도 같은 부류다.
+       */
+      conformance = { comparable: false, reason: 'made-not-observed', recipe: recipe.key }
     } else {
       /*
        * 관측: **바인딩된 자재까지 내려가 센다** — 중간 산물(WIP)은 통과한다.

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

@@ -1,3 +1,5 @@
+import type { ReadBasis } from '@operato/ops-contract'
+
 import { twinWarn } from '../../engine/log.js'
 import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
 
@@ -20,6 +22,26 @@ import { at, idOf, nameIndex, namesFor } from './name-index.js'
 /* 커널 런타임 로드 — 축·관계·속성 선언의 SSOT. 이 파일은 도메인 모양을 알지 않는다. */
 const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, documentPath, isCacheableTense, relationsFrom, relationsTo, propertiesOf, splitRelationIds, tenseOf } =
   require('@operato/ops-contract')
+
+/**
+ * 목록의 답 — **근거는 계약이 닫아 둔 다섯 중 하나다**(`READ_BASIS`).
+ *
+ * 2026-09-18 판정(ADR-0075 결정 3 을 코드에 대어 본 결과): 이 문이 `'rows-scanned'` 를 내고 있었다.
+ * 그것은 출처가 아니라 **우리가 어떻게 셌나**이고, 목록 소비자가 근거로 갈래를 나눌 때 계약에 없는
+ * 값을 만나게 된다. 출처는 `rows` 이고, 훑어 걸렀다는 사실은 `scanned` · `truncated` 가 말한다.
+ * 여기에 칸을 묶어 두면 계약 밖의 값이 다시 생길 때 타입 검사가 잡는다.
+ */
+type AxisListAnswer = {
+  axis: string
+  label: string
+  basis: ReadBasis
+  total: number | null
+  offset: number
+  /** 훑어 센 경우에만 — 몇 줄을 읽었나, 상한에서 잘렸나. */
+  scanned?: number
+  truncated?: boolean
+  [key: string]: unknown
+}
 import { externalIncoming, resolveExternal } from './external-resolver.js'
 
 /**
@@ -131,7 +153,7 @@ export class TwinModelItemQuery {
       const repo = getRepository(row.entity)
       const where = { domain: { id: domainId } as any, instance: { id: inst.id } as any }
       const [rows, total] = await repo.findAndCount({ where, order: row.order, skip, take })
-      return {
+      const answer: AxisListAnswer = {
         axis,
         label: info.label,
         basis: 'rows',
@@ -141,23 +163,27 @@ export class TwinModelItemQuery {
         resourceClassLabels: this.classLabels(inst.model ?? {}),
         items: rows.map((r: any) => this.rowItem(axis, r))
       }
+      return answer
     }
 
     if (row && q) {
       /*
-       * 검색은 아직 DB 로 내리지 않았다. **그 사실을 밝힌다**(`basis: 'rows-scanned'`) —
-       * 흉내로 덮으면 규모가 오는 날까지 아무도 이 한계를 모른다. 훑는 건수를 상한으로 막고,
-       * 상한에 닿았으면 잘렸다고 말한다(알리지 않고 자르지 않는다).
+       * 검색은 아직 DB 로 내리지 않았다. **그 사실을 밝힌다** — 흉내로 덮으면 규모가 오는 날까지
+       * 아무도 이 한계를 모른다. 훑는 건수를 상한으로 막고, 상한에 닿았으면 잘렸다고 말한다
+       * (알리지 않고 자르지 않는다).
+       *
+       * 말하는 자리는 `scanned` · `truncated` 다. 근거(`basis`)는 그대로 `rows` 이고 — 값이 어디서
+       * 왔는지는 훑었든 DB 가 골랐든 같은 행이다 — 계약이 닫아 둔 다섯 밖으로 나가지 않는다.
        */
       const SCAN_MAX = 5000
       const repo = getRepository(row.entity)
       const where = { domain: { id: domainId } as any, instance: { id: inst.id } as any }
       const rows = await repo.find({ where, order: row.order, take: SCAN_MAX })
       const hit = rows.filter((r: any) => matches(this.rowItem(axis, r), q))
-      return {
+      const answer: AxisListAnswer = {
         axis,
         label: info.label,
-        basis: 'rows-scanned',
+        basis: 'rows',
         total: hit.length,
         offset: skip,
         resourceClassLabels: this.classLabels(inst.model ?? {}),
@@ -168,6 +194,7 @@ export class TwinModelItemQuery {
           return { items, names: namesFor(items, nameIndex(inst.model ?? {})) }
         })()
       }
+      return answer
     }
 
     /*
@@ -387,11 +414,28 @@ export class TwinModelItemQuery {
       /* 같은 규칙 — 축 이름이 아니라 선언된 자리에서 읽는다(§axisValueOf). */
       const bucket = snap ? axisValueOf(snap, info) : null
       const found = Array.isArray(bucket) ? bucket.find((o: any) => idOf(o, info) === itemId) : undefined
-      if (!snap || !found) {
+      /*
+       * **상태를 읽었는데 그 개체가 없으면, 그런 개체가 없는 것이다** (2026-09-18).
+       *
+       * 이 갈래가 `!snap || !found` 하나였다. 그래서 없는 식별자로 물어도 「트윈이 실제로 본 것입니다」
+       * 라고 적힌 패널이 돌아왔다 — 화면은 그것을 그려서, 있지도 않은 개체가 값이 비어 있는 개체처럼
+       * 보였다. 문서 축은 같은 물음에 `null` 을 답한다(없는 것은 없다고 답한다). 상태 축도 같다.
+       *
+       * 못 읽은 것은 다른 사실이라 아래에서 따로 답한다 — 「없다」로 접지 않는다.
+       */
+      if (snap && !found) return null
+      if (!snap) {
         return {
           instanceId, axis, label: info.label, itemId,
-          identity: { standardClass: info.standardClass ?? null, typeRole: info.typeRole ?? null, kind: info.kind, gs1Scheme: info.gs1Scheme ?? null },
-          declared: null, observed: found ?? null, observedOnly: true,
+          identity: { standardClass: info.standardClass ?? null, typeRole: info.typeRole ?? null, kind: info.kind, gs1Scheme: info.gs1Scheme ?? null, journalAxis: info.journalAxis ?? null, describedBy: info.describedBy ?? null },
+          declared: null,
+          observed: null,
+          observedOnly: true,
+          /*
+           * **왜 관측 열이 비었나** — 커널이 멈춰 있고 저널로도 되세우지 못했다. 코드는 목록·비교 열이
+           * 쓰는 것과 같은 것을 쓴다(`not-running`) — 같은 사실에 두 낱말을 만들지 않는다.
+           */
+          observedAbsence: 'not-running' as const,
           basis: liveItem ? 'state' : 'journal', observedBasis: liveItem ? 'state' : 'journal', observing: liveItem,
           links: { out: [], incoming: [] }, properties: propertiesOf(axis).map((pr: any) => ({ key: pr.key, label: pr.label, kind: pr.kind, uom: pr.uom ?? null, observedBy: pr.observedBy ?? null })),
           /* 어떤 속성이 **효과가 있나** — 등록부가 말한다(§property-effects). 없는 것은 표시만 된다. */
@@ -402,7 +446,7 @@ export class TwinModelItemQuery {
       const names = namesFor([{ id: itemId, fields: found }], nameIndex(inst.model ?? {}))
       return {
         instanceId, axis, label: info.label, itemId,
-        identity: { standardClass: info.standardClass ?? null, typeRole: info.typeRole ?? null, kind: info.kind, gs1Scheme: info.gs1Scheme ?? null },
+        identity: { standardClass: info.standardClass ?? null, typeRole: info.typeRole ?? null, kind: info.kind, gs1Scheme: info.gs1Scheme ?? null, journalAxis: info.journalAxis ?? null, describedBy: info.describedBy ?? null },
         /*
          * **선언이 없는 축이다.** 두 열 중 왼쪽이 비는 것이 정상이고, 그 사실을 값으로 말한다
          * (`observedOnly`) — 빈 열을 "원본이 침묵했다" 로 읽으면 안 된다. 원본은 애초에 이 축을
@@ -484,7 +528,13 @@ export class TwinModelItemQuery {
         standardClass: info.standardClass ?? null,
         typeRole: info.typeRole ?? null,
         kind: info.kind,
-        gs1Scheme: info.gs1Scheme ?? null
+        gs1Scheme: info.gs1Scheme ?? null,
+        /*
+         * 선언 둘을 그대로 나른다 (ADR-0074) — 이 개체의 이력을 저널의 어느 축으로 묻나,
+         * 그리고 식별자 말고 무엇이 이 개체를 말하나. 화면이 그 목록을 갖지 않게 한다.
+         */
+        journalAxis: info.journalAxis ?? null,
+        describedBy: info.describedBy ?? null
       },
       /*
        * **그릇인가** — 문서에 객체 하나로 있는 축(`productionSpec`)인지.
@@ -831,7 +881,7 @@ export class TwinModelItemQuery {
      */
     for (const l of out) {
       if (l.target?.kind !== 'external' || !l.ids.length) continue
-      const got = await resolveExternal(l.target.entity, domainId, l.ids, m => twinWarn(m))
+      const got = await resolveExternal(l.target.entity, domainId, l.ids, { instanceId: inst.instanceId }, m => twinWarn(m))
       if (got.refs) (l as any).refs = got.refs
       else (l as any).unresolved = got.unresolved
     }

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

@@ -306,6 +306,14 @@ export class TwinModelQuery {
         }
       })())
 
+    /*
+     * 개념 카드가 선언을 그대로 나른다 (2026-09-18, ADR-0074).
+     *
+     * `journalAxis` 는 「이 축의 개체 이력을 저널의 어느 축으로 묻나」이고, 없으면 저널이 그 축으로
+     * 기록하지 않는다는 뜻이다. `describedBy` 는 식별자 말고 무엇이 그 개체를 말하나이다. 둘 다 앱의
+     * 화면 상수에 있었고, 축 이름이 바뀌었을 때 따라오지 못해 세 축의 이력이 조용히 비었다.
+     * 여기서 내보내면 화면은 목록을 갖지 않는다 — 축이 늘어도 화면은 그대로다.
+     */
     const concepts = await Promise.all(
       TWIN_AXES.map(async (a: any) => {
         /*
@@ -325,6 +333,8 @@ export class TwinModelQuery {
             container: false,
             standardClass: a.standardClass,
             typeRole: a.typeRole ?? null,
+            journalAxis: a.journalAxis ?? null,
+            describedBy: a.describedBy ?? null,
             count: null,
             notApplicable: true,
             emptyBecause: 'not-applicable',
@@ -419,6 +429,8 @@ export class TwinModelQuery {
             container: false,
             standardClass: a.standardClass,
             typeRole: a.typeRole ?? null,
+            journalAxis: a.journalAxis ?? null,
+            describedBy: a.describedBy ?? null,
             count: Array.isArray(bucket) ? bucket.length : null,
             /*
              * **수 하나가 뜻을 바꾸는 자리** (2026-08-23).
@@ -461,6 +473,8 @@ export class TwinModelQuery {
           container: !Array.isArray(raw) && raw != null,
           standardClass: a.standardClass,
           typeRole: a.typeRole ?? null,
+          journalAxis: a.journalAxis ?? null,
+          describedBy: a.describedBy ?? null,
           count: entity ? inRows : inDocument,
           /*
            * 비었으면 왜 비었는지 — 선언 쪽은 세 갈래다.

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

@@ -0,0 +1,75 @@
+/*
+ * What an area id is — the host's answer for `external: 'space.area'`.
+ *
+ * The contract declares a location's parent as another location or, when no location has that id, an area of the
+ * space (`axis-or-external`), and says the host resolves the external half. Nothing registered a resolver, so on
+ * 2026-09-18 every location in the running twin showed its parent as "no component can resolve this relation" —
+ * the areas were in this package's own table all along.
+ *
+ * The lookup is (domain, space, areaId), the table's own unique key: an `areaId` is unique inside a space, so a
+ * tenant can hold the same id in two spaces. The space comes from the twin the relation belongs to, which is why
+ * `resolve` is given the instance (external-resolver.ts `ExternalResolveContext`). Looking up by tenant alone
+ * would answer another space's name as this location's parent.
+ *
+ * No `href`: the screen that opens an area belongs to the product app, and putting its route here would fix a
+ * product screen's address in this package. With no href the screen shows the name and makes no link — that is
+ * what the field is for (no dead links). A route is registered the day a screen needs it.
+ */
+import { getRepository } from '@things-factory/shell'
+import { In } from 'typeorm'
+
+import { registerExternalResolver, type ExternalRef, type ExternalResolveContext } from '../twin-model/external-resolver.js'
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+import { TwinSpace } from './twin-space.js'
+import { TwinArea } from './twin-area.js'
+
+/** The contract's word for this target. Must match `target.entity` or it attaches to no relation. */
+export const SPACE_AREA_ENTITY = 'space.area'
+
+export async function resolveAreas(
+  domainId: string,
+  ids: readonly string[],
+  context: ExternalResolveContext,
+  warn?: (msg: string) => void
+): Promise<ExternalRef[]> {
+  const wanted = [...new Set(ids.map(String).filter(Boolean))]
+  if (!wanted.length) return []
+
+  /* Which space is this twin in? A twin with no space has no areas to point at — every id is then missing. */
+  const inst = await getRepository(TwinInstance).findOne({
+    where: { domain: { id: domainId } as any, instanceId: context.instanceId }
+  })
+  const spaceId = inst?.spaceId
+  if (!spaceId) {
+    warn?.(`[area-resolver] twin "${context.instanceId}" is in no space — its parent ids cannot be areas`)
+    return wanted.map(id => ({ id, missing: true }))
+  }
+  const space = await getRepository(TwinSpace).findOne({ where: { domain: { id: domainId } as any, spaceId } })
+  if (!space) {
+    warn?.(`[area-resolver] space "${spaceId}" of twin "${context.instanceId}" is not in this tenant`)
+    return wanted.map(id => ({ id, missing: true }))
+  }
+
+  const rows = await getRepository(TwinArea).find({
+    where: { domain: { id: domainId } as any, space: { id: space.id } as any, areaId: In(wanted) }
+  })
+  const byId = new Map(rows.map(r => [r.areaId, r]))
+
+  /* An id that is in no area of this space is said to be missing — it is not dropped from the answer. */
+  return wanted.map(id => {
+    const area = byId.get(id)
+    if (!area) return { id, missing: true }
+    return area.name ? { id, name: area.name } : { id }
+  })
+}
+
+/** Registered at boot, once — the same shape as the reference link resolver. */
+export function installAreaResolver(warn?: (msg: string) => void): void {
+  registerExternalResolver(
+    {
+      entity: SPACE_AREA_ENTITY,
+      resolve: (domainId, ids, context) => resolveAreas(domainId, ids, context, warn)
+    },
+    warn
+  )
+}

package/test/actuation-verification-state.test.ts

@@ -13,7 +13,7 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 
-import { actuationOutcomePatch } from '../server/service/reference/actuation-verification.js'
+import { actuationAddressed, actuationOutcomePatch, actuationResetPatch } from '../server/service/reference/actuation-verification.js'
 
 const AT = '2026-09-16T04:05:06.000Z'
 
@@ -92,3 +92,48 @@ test('★ 기록하는 자리가 판단을 쓰고 그 값을 저장한다 —
   assert.match(record, /actuationOutcomePatch\(/, '판단을 부르지 않는다 — 두 벌이 된다')
   assert.match(record, /\.update\(/, '부른 결과를 저장하지 않는다')
 })
+
+test('★ 주소를 바꾸는 저장은 검증을 되돌린다 — 지난 왕복은 지난 주소의 이야기다', () => {
+  /*
+   * 2026-09-18 실측(ADR-0046 ② 를 코드에 대어 본 결과): 칸 셋도 왕복의 결과를 적는 자리도 섰는데,
+   * `verified` 인 연결의 주소를 바꿔도 그대로 `verified` 였다. 화면은 다른 공장을 가리키는 연결을
+   * 「확인됨」으로 그린다.
+   */
+  const before = { intakeEndpoint: 'https://a.example/intake', intakeSiteId: 'line-a', intakeSecret: 's1' }
+  const moved = actuationResetPatch(before, { ...before, intakeEndpoint: 'https://b.example/intake' })
+  assert.deepEqual(moved, { actuationState: 'unverified', actuationVerifiedAt: null, actuationFailure: null })
+  assert.ok(actuationResetPatch(before, { ...before, intakeSiteId: 'line-b' }), '받는 사이트가 바뀌었다')
+  assert.ok(actuationResetPatch(before, { ...before, intakeSecret: 's2' }), '저쪽이 우리를 못 알아보면 그 왕복은 다시 성립하지 않는다')
+  assert.ok(actuationResetPatch(undefined, before), '처음 적는 주소도 아직 왕복이 없다')
+})
+
+test('주소가 그대로면 검증도 그대로 — 이름만 고쳤다고 되돌리지 않는다', () => {
+  const cfg = { intakeEndpoint: 'https://a.example/intake', intakeSiteId: 'line-a', intakeSecret: 's1' }
+  assert.equal(actuationResetPatch(cfg, { ...cfg, label: '군산 1라인' }), null)
+  /* 끝의 빗금은 같은 주소다 — 그것으로 되돌리면 저장할 때마다 초록이 사라진다. */
+  assert.equal(actuationResetPatch(cfg, { ...cfg, intakeEndpoint: 'https://a.example/intake/' }), null)
+  /* 가려진 비밀값은 저장 쪽이 병합해 옛 값 그대로 온다(그래서 여기까지 같은 값이 온다). */
+  assert.equal(actuationResetPatch(cfg, { ...cfg }), null)
+})
+
+test('★ 보낼 주소가 적힌 연결에만 검증 상태를 말한다 — 읽기만 하는 연결에 할 일을 만들지 않는다', () => {
+  assert.equal(actuationAddressed({ intakeEndpoint: 'https://a.example/intake', intakeSiteId: 'line-a' }), true)
+  assert.equal(actuationAddressed({ intakeEndpoint: 'https://a.example/intake', siteId: 'line-a' }), true, 'siteId 가 그 자리를 대신한다')
+  assert.equal(actuationAddressed({ intakeSiteId: 'line-a' }), false, '주소가 없으면 아무 데도 안 간다')
+  assert.equal(actuationAddressed({ intakeEndpoint: 'https://a.example/intake' }), false, '받는 사이트를 모르면 못 보낸다')
+  assert.equal(actuationAddressed(undefined), false)
+})
+
+test('★ 읽기 문이 그 상태를 싣는다 — 저장돼 있어도 나르지 않으면 화면이 볼 길이 없다', () => {
+  /*
+   * 2026-09-18 실측: 칸 셋은 2026-09 부터 서 있었고 왕복의 결과도 적히는데, 목록도 상세도 그 값을
+   * 싣지 않았다. 저장된 사실이 아무에게도 닿지 않는 상태였다.
+   */
+  const src = readFileSync(new URL('../server/service/reference/reference-resolver.ts', import.meta.url).pathname, 'utf-8')
+  for (const door of ['async twinReferences(', 'async twinReference(']) {
+    const at = src.indexOf(door)
+    assert.ok(at > 0, `${door} 를 못 찾았다 — 읽는 쪽이 깨졌다`)
+    const body = src.slice(at, at + 3000)
+    assert.ok(/actuationState/.test(body), `${door} 가 검증 상태를 싣지 않는다`)
+  }
+})

package/test/area-resolver-db.test.ts

@@ -0,0 +1,110 @@
+/*
+ * What an area id is, and whose area it is.
+ *
+ * The item panel shows a location's parent. When the parent is an area, the host answers what that id is
+ * (`external: 'space.area'`). Nothing registered that answer until 2026-09-18, so every location's parent read
+ * "no component can resolve this relation" on the running twin.
+ *
+ * The lookup is (domain, space, areaId) — the area table's own unique key. An `areaId` is unique inside a space,
+ * so the same id can exist in two spaces of one tenant; the space comes from the twin the relation belongs to.
+ * Held here: the name of this twin's area, "missing" for an id that is in no area of this space, and another
+ * space's area of the same id never answering.
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+const { resolveAreas, installAreaResolver, SPACE_AREA_ENTITY } = req('../dist-server/service/twin-space/area-resolver.js')
+const { externalResolverEntities, clearExternalResolvers, resolveExternal } = req('../dist-server/service/twin-model/external-resolver.js')
+const { TwinSpace } = req('../dist-server/service/twin-space/twin-space.js')
+const { TwinArea } = req('../dist-server/service/twin-space/twin-area.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+let otherDomainId: string
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  const d = await ds.getRepository(Domain).save({ name: 'area-test', subdomain: 'area-test' } as any)
+  const other = await ds.getRepository(Domain).save({ name: 'area-other', subdomain: 'area-other' } as any)
+  domainId = d.id
+  otherDomainId = other.id
+
+  const spaces = ds.getRepository(TwinSpace)
+  const north = await spaces.save({ domain: { id: domainId }, spaceId: 'north', name: 'North site' } as any)
+  const south = await spaces.save({ domain: { id: domainId }, spaceId: 'south', name: 'South site' } as any)
+  const far = await spaces.save({ domain: { id: otherDomainId }, spaceId: 'far', name: 'Far site' } as any)
+
+  const areas = ds.getRepository(TwinArea)
+  /* The same areaId in two spaces of one tenant — that is what the space scope is for. */
+  await areas.save({ domain: { id: domainId }, space: { id: north.id }, areaId: 'hall-a', name: 'North Hall A' } as any)
+  await areas.save({ domain: { id: domainId }, space: { id: south.id }, areaId: 'hall-a', name: 'South Hall A' } as any)
+  await areas.save({ domain: { id: otherDomainId }, space: { id: far.id }, areaId: 'hall-a', name: 'Far Hall A' } as any)
+  /* An area with no name — the answer then carries the id alone, and does not invent one. */
+  await areas.save({ domain: { id: domainId }, space: { id: north.id }, areaId: 'annex' } as any)
+
+  const instances = ds.getRepository(TwinInstance)
+  await instances.save({ domain: { id: domainId }, instanceId: 'north-twin', kind: 'wms', restartPolicy: 'resume', purpose: 'operational', spaceId: 'north', status: 'stopped' } as any)
+  await instances.save({ domain: { id: domainId }, instanceId: 'south-twin', kind: 'wms', restartPolicy: 'resume', purpose: 'operational', spaceId: 'south', status: 'stopped' } as any)
+  await instances.save({ domain: { id: domainId }, instanceId: 'homeless-twin', kind: 'wms', restartPolicy: 'resume', purpose: 'operational', status: 'stopped' } as any)
+})
+
+after(async () => {
+  clearExternalResolvers()
+  await ds?.destroy()
+})
+
+test('an area of this twin comes back with its name', async () => {
+  const refs = await resolveAreas(domainId, ['hall-a'], { instanceId: 'north-twin' })
+  assert.deepEqual(refs, [{ id: 'hall-a', name: 'North Hall A' }])
+})
+
+test('the same areaId in another space of the same tenant never answers', async () => {
+  const south = await resolveAreas(domainId, ['hall-a'], { instanceId: 'south-twin' })
+  assert.deepEqual(south, [{ id: 'hall-a', name: 'South Hall A' }], 'each twin sees its own space')
+  const other = await resolveAreas(otherDomainId, ['hall-a'], { instanceId: 'north-twin' })
+  assert.deepEqual(other, [{ id: 'hall-a', missing: true }], 'a twin of another tenant is not this tenant’s twin')
+})
+
+test('an id that is in no area of this space is missing — it is not dropped', async () => {
+  const refs = await resolveAreas(domainId, ['hall-a', 'nowhere'], { instanceId: 'north-twin' })
+  assert.deepEqual(refs, [{ id: 'hall-a', name: 'North Hall A' }, { id: 'nowhere', missing: true }])
+})
+
+test('an area with no name answers with the id alone — no name is invented', async () => {
+  const refs = await resolveAreas(domainId, ['annex'], { instanceId: 'north-twin' })
+  assert.deepEqual(refs, [{ id: 'annex' }])
+})
+
+test('a twin with no space cannot have area parents, and says so', async () => {
+  const warned: string[] = []
+  const refs = await resolveAreas(domainId, ['hall-a'], { instanceId: 'homeless-twin' }, m => warned.push(m))
+  assert.deepEqual(refs, [{ id: 'hall-a', missing: true }])
+  assert.equal(warned.length, 1, 'the reason is said once, not swallowed')
+})
+
+test('the resolver is registered under the word the contract uses, and answers through the seam', async () => {
+  clearExternalResolvers()
+  installAreaResolver()
+  assert.ok(externalResolverEntities().includes(SPACE_AREA_ENTITY))
+  assert.equal(SPACE_AREA_ENTITY, 'space.area')
+  const got = await resolveExternal(SPACE_AREA_ENTITY, domainId, ['hall-a'], { instanceId: 'north-twin' })
+  assert.deepEqual(got, { refs: [{ id: 'hall-a', name: 'North Hall A' }] })
+})

package/test/axis-declaration-passthrough-db.test.ts

@@ -0,0 +1,152 @@
+/*
+ * 축의 선언이 읽기 문을 그대로 지나간다 — `journalAxis` · `describedBy` (ADR-0074).
+ *
+ * 둘은 앱의 화면 상수에 있던 것이다. 그 자리에 있는 동안 축 이름이 한 세대 바뀌자 표가 따라오지
+ * 못했고, 로케이션 · 오더 · 품목의 360 은 저널을 **묻지도 않은 채** 「이 개념은 이력 축이 없다」를
+ * 그렸다. 계약으로 올라온 지금, 화면이 다시 자기 표를 만들지 않으려면 읽기 문이 그 값을 날라야 한다.
+ *
+ * 여기서 지키는 것은 하나다: **계약이 말한 값이 그대로 도착한다.** 값을 이 파일에 다시 적지 않는다 —
+ * 다시 적으면 계약이 바뀔 때 시험이 같이 썩고, 지나가는지를 못 본다.
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+const { TwinEngine } = req('../dist-server/engine/index.js')
+const { TwinModelItemQuery } = req('../dist-server/service/twin-model/twin-model-item-query.js')
+const { axisInfo } = req('@operato/ops-contract')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let q: any
+let ctx: any
+const INSTANCE = 'declaration-probe'
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  const d = await ds.getRepository(Domain).save({ name: 'decl-test', subdomain: 'decl-test' } as any)
+  q = new TwinModelItemQuery()
+  ctx = { state: { domain: { id: d.id } } }
+
+  /*
+   * 축마다 **자기 모양대로** 한 항목씩 — 설명 칸이 축마다 다른 이름으로 온다는 것이 아래 시험의 요점이다.
+   * (등급 넷과 검사 명세는 `name` 으로 들어오는데 형 선언은 `description` 을 말한다 — 실측, 2026-09-18.)
+   */
+  await TwinEngine.ingestMaster(d.id, {
+    source: INSTANCE,
+    system: 'wms',
+    siteName: 'declaration site',
+    space: { width: 40, depth: 20, unit: 'm' },
+    locations: [{ id: 'bin-1', type: 'storage', role: 'location', name: 'Bin 1', capacity: 10 }],
+    equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'bin-1' }],
+    equipmentClasses: [{ id: 'EC-FORKLIFT', name: '지게차' }],
+    materialClasses: [{ id: 'MC-BOX', name: '상자류' }],
+    materialDefinitions: [{ id: 'MD-BOX-01', name: '표준 상자', materialClassIds: ['MC-BOX'] }],
+    testSpecifications: [{ id: 'TS-DROP', name: '낙하 시험', version: '1', criteria: [] }]
+  }, 'reset')
+})
+
+after(async () => {
+  await TwinEngine.stop(ctx.state.domain.id, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('★ 자리의 이력 축과 설명 필드가 계약이 말한 그대로 도착한다', async () => {
+  const item = await q.twinModelItem(INSTANCE, 'locations', 'bin-1', ctx)
+  const declared = axisInfo('locations')
+  assert.ok(declared?.journalAxis, '계약이 자리의 저널 축을 말하지 않는다 — 시험의 기준이 비었다')
+  assert.equal(item.identity.journalAxis, declared.journalAxis)
+  assert.deepEqual(item.identity.describedBy, declared.describedBy)
+})
+
+test('★ 설비도 같은 자리에서 자기 선언을 받는다 — 축마다 다른 값이 온다', async () => {
+  const item = await q.twinModelItem(INSTANCE, 'equipment', 'fk-1', ctx)
+  const declared = axisInfo('equipment')
+  assert.equal(item.identity.journalAxis, declared!.journalAxis)
+  assert.deepEqual(item.identity.describedBy, declared!.describedBy)
+  /* 두 축이 같은 값을 받으면 「지나간다」를 못 본 것이다. */
+  assert.notEqual(declared!.journalAxis, axisInfo('locations')!.journalAxis)
+})
+
+test('★ 저널이 그 축으로 기록하지 않는 개념은 null 로 온다 — 없는 것을 이름으로 채우지 않는다', async () => {
+  const declared = axisInfo('operations')
+  assert.equal(declared?.journalAxis, undefined, '명세 축은 저널 축을 갖지 않는다')
+  /* 이 트윈에는 공정 선언이 없다 — 선언이 없는 축도 문은 같은 모양으로 답한다. */
+  const item = await q.twinModelItem(INSTANCE, 'operations', 'no-such-operation', ctx)
+  if (item) assert.equal(item.identity.journalAxis, null, '없는 것은 null 이고 빈 문자열이 아니다')
+})
+
+/*
+ * 상태 축에 없는 개체를 물으면 — **그런 개체가 없다**고 답한다.
+ *
+ * 2026-09-18, 도는 서버에서: 지어낸 작업 식별자(`tasks:T-1`)로 물었더니 패널이 하나 돌아왔고 화면은
+ * 「트윈이 실제로 본 것입니다」라고 적었다. 있지도 않은 개체가 **값이 비어 있는 개체**처럼 보였다.
+ * 갈래가 `!snap || !found` 하나여서 두 사실이 한 답으로 접혔기 때문이다.
+ *
+ *   상태를 읽었는데 없다   → 그런 개체가 없다(문서 축과 같은 `null`)
+ *   상태를 못 읽었다       → 모른다. 이유를 코드로 말한다(`not-running`)
+ */
+test('★ 상태를 읽었는데 그 개체가 없으면 없다고 답한다 — 빈 개체를 만들지 않는다', async () => {
+  const gone = await q.twinModelItem(INSTANCE, 'tasks', 'NO-SUCH-TASK-ID', ctx)
+  assert.equal(gone, null, '없는 개체에 패널을 돌려주면 화면이 그것을 그린다')
+})
+
+test('★ 같은 물음을 문서 축에 해도 같은 답이다 — 축마다 다른 말을 하지 않는다', async () => {
+  const gone = await q.twinModelItem(INSTANCE, 'locations', 'NO-SUCH-LOCATION', ctx)
+  assert.equal(gone, null)
+})
+
+test('★ 있는 개체는 그대로 답한다 — 위의 고침이 다 지워 버리지 않았는지', async () => {
+  const item = await q.twinModelItem(INSTANCE, 'locations', 'bin-1', ctx)
+  assert.ok(item, '있는 개체가 사라졌다')
+  assert.equal(item.itemId, 'bin-1')
+})
+
+/*
+ * **선언이 고른 칸이 실제 항목에 있는가** (2026-09-18).
+ *
+ * `describedBy` 를 형 선언에서 뽑아 적었더니 여섯 축이 빗나갔다 — 등급 넷 · 품목 정의 · 검사 명세는
+ * 형이 `description` 을 말하는데 들어오는 자료는 `name` 을 든다. 화면은 오류 없이 **밑줄이 없는
+ * 제목**만 그렸다(도는 트윈에서 실측). 계약과 자료가 갈린 것을 시험이 못 잡았던 이유는, 그 시험이
+ * 「그 이름이 계약 어딘가에 선언돼 있나」까지만 봤기 때문이다.
+ *
+ * 그래서 여기서는 **들어온 항목**에 대고 잰다: 선언한 칸 중 적어도 하나가 그 항목에 값으로 있어야 한다.
+ */
+test('★ 선언이 고른 칸 중 하나는 실제 항목이 들고 있다 — 계약과 자료가 갈리면 밑줄이 사라진다', async () => {
+  const sample: Record<string, string> = {
+    locations: 'bin-1',
+    equipment: 'fk-1',
+    equipmentClasses: 'EC-FORKLIFT',
+    materialClasses: 'MC-BOX',
+    materialDefinitions: 'MD-BOX-01',
+    testSpecifications: 'TS-DROP'
+  }
+  const missing: string[] = []
+  for (const [axis, itemId] of Object.entries(sample)) {
+    const item = await q.twinModelItem(INSTANCE, axis, itemId, ctx)
+    assert.ok(item, `${axis}: 픽스처가 안 들어갔다 — 이 시험이 아무것도 재지 못한다`)
+    const keys: string[] = item.identity?.describedBy ?? []
+    assert.ok(keys.length, `${axis}: 계약이 설명 칸을 말하지 않는다`)
+    const has = keys.some(k => {
+      const v = (item.observed ?? {})[k] ?? (item.declared ?? {})[k]
+      return v != null && v !== ''
+    })
+    if (!has) missing.push(`${axis}: 선언은 [${keys.join(', ')}] 인데 항목이 든 것은 [${Object.keys(item.declared ?? {}).join(', ')}]`)
+  }
+  assert.deepEqual(missing, [], missing.join('\n'))
+})