@things-factory/headless-twin 10.1.28 → 10.1.29

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
     }
 
     /*

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/axis-declaration-passthrough-db.test.ts

@@ -43,13 +43,21 @@ before(async () => {
   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' }]
+    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')
 })
 
@@ -108,3 +116,37 @@ test('★ 있는 개체는 그대로 답한다 — 위의 고침이 다 지워
   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'))
+})

package/test/lineage-survives-restart.test.ts

@@ -209,6 +209,21 @@ test('계보를 거슬러 올라가 선언과 나란히 놓는다 — 그 차이
   assert.equal(steel.matches, true)
 })
 
+test('★ 만든 것을 관측하지 못했으면 「다르다」고 하지 않는다 — 안 본 것과 어긋난 것은 다른 사실이다', async () => {
+  const q = new TwinLineageQuery()
+  const ctx = { state: { domain: { id: domainId } } } as any
+  /*
+   * 완제품 클래스의 개체이지만 저널에 그것을 낸 변환이 없다 — 자재로도 이어지고 레시피도 하나다.
+   * 예전에는 여기서 셈이 그대로 돌아 관측을 전부 0 으로 적고 「레시피와 다릅니다」를 냈다
+   * (2026-09-18 :3000 에서 카메라 로트 23 줄이 그렇게 보였다).
+   */
+  const lin = await q.twinItemLineage(INSTANCE, `urn:epc:id:sgtin:${CP}.078101.999999`, ctx)
+  assert.equal(lin.conformance.comparable, false, `관측이 없는데 견주었다: ${JSON.stringify(lin.conformance?.lines?.slice(0, 2))}`)
+  assert.equal(lin.conformance.reason, 'made-not-observed')
+  assert.ok(lin.conformance.recipe, '어느 레시피와 견주려 했는지는 말한다 — 사람이 다음 걸음을 안다')
+  assert.equal(lin.basis.transformationsRead >= 0, true)
+})
+
 test('바인딩이 없으면 비교하지 않고 이유를 알린다 — 짐작으로 이으면 거짓 진단이 된다', async () => {
   const q = new TwinLineageQuery()
   const ctx = { state: { domain: { id: domainId } } } as any

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

@@ -114,12 +114,29 @@ test('아직 문서에 사는 축도 열린다 — 이주 전이라고 안 보
 
 test('검색이 전수 조회라는 사실을 드러낸다 — 감추면 한계를 아무도 모른다', async () => {
   const r = await q.twinModelEntities(INSTANCE, 'equipment', ctx, 'weld')
-  assert.equal(r.basis, 'rows-scanned', '아직 DB 로 내리지 않았다는 사실이 응답에 있다')
   assert.equal(r.total, 2)
+  /* 훑어 걸렀다는 사실은 **이 두 칸이** 말한다(근거가 아니라 셈의 한계다). */
+  assert.equal(typeof r.scanned, 'number', '몇 줄을 읽었는지 말하지 않는다')
   assert.equal(r.truncated, false, '상한에 닿지 않았으면 잘리지 않았다고 말한다')
   assert.deepEqual(r.items.map((i: any) => i.id).sort(), ['welder-1', 'welder-2'])
 })
 
+test('★ 근거는 계약이 닫아 둔 다섯 안에서만 답한다', async () => {
+  /*
+   * 2026-09-18 판정(ADR-0075 결정 3 을 코드에 대어 본 결과): 검색 갈래가 `'rows-scanned'` 를 냈다.
+   * 그것은 출처가 아니라 우리가 어떻게 셌나이고, 목록 소비자는 계약에 없는 값을 만난다. 출처는
+   * 훑었든 DB 가 골랐든 같은 행이므로 `rows` 다.
+   */
+  const { READ_BASIS } = req('@operato/ops-contract')
+  const answers = [
+    await q.twinModelEntities(INSTANCE, 'equipment', ctx, 'weld'),
+    await q.twinModelEntities(INSTANCE, 'equipment', ctx),
+    await q.twinModelEntities(INSTANCE, 'recipes', ctx)
+  ]
+  for (const a of answers) assert.ok(READ_BASIS.includes(a.basis), `계약 밖의 근거 '${a.basis}'`)
+  assert.equal(answers[0].basis, 'rows', '훑어 세도 값이 온 곳은 행이다')
+})
+
 test('모르는 축은 거절한다 — 빈 목록은 "없다" 로 읽힌다', async () => {
   await assert.rejects(() => q.twinModelEntities(INSTANCE, 'nosuch', ctx), /unknown concept axis/)
   await assert.rejects(() => q.twinModelItem(INSTANCE, 'nosuch', 'x', ctx), /unknown concept axis/)