@things-factory/headless-twin 10.1.27 → 10.1.28

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/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,110 @@
+/*
+ * 축의 선언이 읽기 문을 그대로 지나간다 — `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 } } }
+
+  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' }]
+  }, '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')
+})

package/test/external-resolver.test.ts

@@ -28,6 +28,12 @@ import {
 
 const AREA = 'space.area'
 
+/*
+ * 어느 트윈의 관계인지 — `resolve` 는 이것을 함께 받는다(2026-09-18). 밖의 id 는 도메인에서 유일하지
+ * 않아서(구역 id 는 공간 안에서만 유일), 문맥 없이 답하면 남의 공간 이름이 이 자리의 부모로 보인다.
+ */
+const CTX = { instanceId: 'probe-twin' }
+
 /* ── 못 풀면 못 푼다고 말한다 ────────────────────────────────────────────── */
 
 test('★ 꽂힌 것이 없으면 「해소기가 없다」고 말한다 — 「없다」가 아니다', async () => {
@@ -36,7 +42,7 @@ test('★ 꽂힌 것이 없으면 「해소기가 없다」고 말한다 — 「
    * 사람이 할 일이 다르다 — 앞은 자료를 채울 일이고 뒤는 해소기를 꽂을 일이다.
    */
   clearExternalResolvers()
-  const got = await resolveExternal(AREA, 'd1', ['LINE-CAM'])
+  const got = await resolveExternal(AREA, 'd1', ['LINE-CAM'], CTX)
 
   assert.equal(got.unresolved, 'no-resolver')
   assert.equal(got.refs, undefined)
@@ -47,7 +53,7 @@ test('★ 해소기가 터져도 360 을 죽이지 않는다 — 알리고 못
   const said: string[] = []
   registerExternalResolver({ entity: AREA, resolve: async () => { throw new Error('DB down') } })
 
-  const got = await resolveExternal(AREA, 'd1', ['X'], m => said.push(m))
+  const got = await resolveExternal(AREA, 'd1', ['X'], CTX, m => said.push(m))
 
   assert.equal(got.unresolved, 'failed')
   assert.ok(said.some(m => m.includes('DB down')), '사유를 삼켰다')
@@ -62,7 +68,7 @@ test('★ 이름과 갈 곳을 낸다 — 막다른 링크를 만들지 않으
     resolve: async (_d, ids) => ids.map(id => ({ id, name: `라인 ${id}`, href: `/areas/${id}` }))
   })
 
-  const got = await resolveExternal(AREA, 'd1', ['LINE-CAM'])
+  const got = await resolveExternal(AREA, 'd1', ['LINE-CAM'], CTX)
   assert.equal(got.refs?.[0].name, '라인 LINE-CAM')
   assert.equal(got.refs?.[0].href, '/areas/LINE-CAM')
 })
@@ -72,7 +78,7 @@ test('★ 없는 id 는 없다고 말한다 — 답에서 빼지 않는다', asy
   clearExternalResolvers()
   registerExternalResolver({ entity: AREA, resolve: async (_d, ids) => ids.map(id => ({ id, missing: true })) })
 
-  const got = await resolveExternal(AREA, 'd1', ['사라진구역'])
+  const got = await resolveExternal(AREA, 'd1', ['사라진구역'], CTX)
   assert.equal(got.refs?.length, 1)
   assert.equal(got.refs?.[0].missing, true)
 })
@@ -166,6 +172,6 @@ test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면
   clearExternalResolvers()
   assert.deepEqual(externalResolverEntities(), [], '지우기가 안 듣는다')
   registerExternalResolver({ entity: AREA, resolve: async (_d, ids) => ids.map(id => ({ id })) })
-  const got = await resolveExternal(AREA, 'd', ['X'])
+  const got = await resolveExternal(AREA, 'd', ['X'], CTX)
   assert.equal(got.refs?.length, 1, '꽂았는데 안 불린다')
 })