@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/project-structure-db.test.ts

@@ -0,0 +1,226 @@
+/*
+ * 구조 투영 — `TwinModelDef`(커널 입력 문서) → **표준 엔티티 행**(ADR-0032).
+ *
+ * ── 왜 DB 검사인가 ─────────────────────────────────────────────────────────
+ * 이 코드의 값어치는 **DB 가 대신 지켜 주는 것**에 있다 — 끊어진 참조를 FK 가 막고, 원본 없는 행을
+ * NOT NULL 이 막는다. 순수 함수 검사로는 그게 하나도 확인되지 않는다. 그래서 실제 DataSource 를
+ * 세운다(멀티DB 규약상 sqlite 로 도는 것이 5개 드라이버 공통의 최소선이기도 하다).
+ *
+ * ── 이 검사가 지키는 것 ────────────────────────────────────────────────────
+ *  · 문서의 세 축이 행으로 선다
+ *  · 설비→자리가 **진짜 FK** 로 이어진다(문자열 대조가 아니라)
+ *  · 끊어진 참조는 **이름을 대고 보고**되고, 행 자체는 남는다(막지 않되 침묵하지 않는다)
+ *  · **전량 교체** — 두 번 돌려도 늘지 않고, 원본에서 사라진 것은 행에서도 사라진다
+ *  · 원본 표식(`sourceRef`·`ingestedAt`) 없는 행은 만들 수 없다(캐시라는 사실이 구조로 지켜진다)
+ *  · 소요시간은 ISO 8601 **문자열 그대로** 남는다(분으로 접으면 초가 조용히 사라진다)
+ */
+import { test, before, after, beforeEach } 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 { projectStructure } = req('../dist-server/service/twin-model/project-structure.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { TwinSpace } = req('../dist-server/service/twin-space/twin-space.js')
+const { TwinArea } = req('../dist-server/service/twin-space/twin-area.js')
+const { TwinLocation } = req('../dist-server/service/twin-model/twin-location.js')
+const { TwinEquipment } = req('../dist-server/service/twin-model/twin-equipment.js')
+const { TwinOperation } = req('../dist-server/service/twin-model/twin-operation.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'projection-probe'
+const SOURCE = 'projection-probe'
+
+/** 실제 트레일러 트윈과 같은 모양의 문서(축소판). */
+const model = () => ({
+  locations: [
+    { id: 'cut-station', type: 'cut-station', name: '프레임 절단', capacity: 20, parentId: 'a-floor' },
+    { id: 'weld-station', type: 'weld-station', capacity: 20, parentId: 'a-floor' },
+    { id: 'orphan-bin', type: 'storage', capacity: 5, parentId: 'no-such-area' }
+  ],
+  equipment: [
+    { id: 'cutter-1', kind: 'cutter', name: '절단기 1호', homeLocation: 'cut-station', mtbfMs: 3600000,
+      properties: [{ id: 'speed', value: '1.2', dataType: 'xs:double', uom: 'MTS' }] },
+    { id: 'welder-1', kind: 'welder', homeLocation: 'weld-station' },
+    { id: 'ghost-1', kind: 'welder', homeLocation: 'no-such-location' }
+  ],
+  operations: [
+    { key: 'cut', label: 'twin.tpl.x.cut', intent: 'process', locationType: 'cut-station', resourceType: 'cutter',
+      duration: 'PT1H10M30S', variability: { distribution: 'triangular', min: 'PT1H', max: 'PT1H30M' },
+      parameters: [{ id: 'yield', value: '0.995' }],
+      /* 네 자원 명세 — 설비는 `resourceType`, 나머지 셋은 아래. */
+      personnelSpecification: [{ personnelClass: 'cutter-op', quantity: 1 }],
+      physicalAssetSpecification: [{ assetClass: 'jig', quantity: 1 }],
+      materialSpecification: [{ materialDefinition: 'steel', use: 'consumed', quantity: 2 }] }
+  ]
+})
+
+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: 'projection-test', subdomain: 'projection-test' } as any)
+  domainId = d.id
+
+  await ds.getRepository(TwinInstance).save({
+    domain: { id: domainId },
+    instanceId: INSTANCE,
+    kind: 'mes',
+    realityMode: 'sim-experiment',
+    purpose: 'operational',
+    status: 'stopped',
+    model: {}
+  } as any)
+
+  /* 구역은 model 밖(호스트 개념) — 자리가 FK 로 이걸 가리킨다. */
+  const space = await ds.getRepository(TwinSpace).save({ domain: { id: domainId }, spaceId: 'sp-1', name: '공장' } as any)
+  await ds.getRepository(TwinArea).save({ domain: { id: domainId }, space: { id: space.id }, areaId: 'a-floor', name: '생산 플로어' } as any)
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+beforeEach(async () => {
+  await projectStructure(domainId, INSTANCE, model(), SOURCE)
+})
+
+test('문서의 세 축이 행으로 선다', async () => {
+  assert.equal(await ds.getRepository(TwinLocation).count(), 3)
+  assert.equal(await ds.getRepository(TwinEquipment).count(), 3)
+  assert.equal(await ds.getRepository(TwinOperation).count(), 1)
+})
+
+test('설비→자리가 진짜 FK 로 이어진다 — 문자열 대조가 아니다', async () => {
+  const eq = await ds.getRepository(TwinEquipment).findOne({ where: { equipmentId: 'cutter-1' }, relations: ['homeLocation'] })
+  assert.equal(eq?.homeLocation?.locationId, 'cut-station', 'FK 로 자리를 따라갈 수 있어야 한다')
+  /* 자리 쪽에서도 같은 행이다 — 문자열이었으면 같은 값이지만 같은 행은 아니다. */
+  const loc = await ds.getRepository(TwinLocation).findOne({ where: { locationId: 'cut-station' } })
+  assert.equal(eq?.homeLocation?.id, loc?.id)
+})
+
+test('자리→구역이 FK 로 이어진다 — 커널이 "밖" 이라 부른 참조가 호스트에서는 평범한 FK 다', async () => {
+  const loc = await ds.getRepository(TwinLocation).findOne({ where: { locationId: 'cut-station' }, relations: ['area'] })
+  assert.equal(loc?.area?.areaId, 'a-floor')
+})
+
+test('끊어진 참조는 이름을 대고 보고된다 — 막지 않되 침묵하지 않는다', async () => {
+  const report = await projectStructure(domainId, INSTANCE, model(), SOURCE)
+  assert.deepEqual(report.unresolvedHome, ['ghost-1→no-such-location'])
+  assert.deepEqual(report.unresolvedArea, ['orphan-bin→no-such-area'])
+
+  /* 행 자체는 남는다 — 참조 하나 때문에 설비가 통째로 사라지면 그게 더 나쁜 거짓말이다. */
+  const ghost = await ds.getRepository(TwinEquipment).findOne({ where: { equipmentId: 'ghost-1' }, relations: ['homeLocation'] })
+  assert.ok(ghost, '끊어진 참조를 가진 설비도 행으로 남는다')
+  assert.equal(ghost?.homeLocation, null, '이을 수 없는 참조는 비운다(엉뚱한 자리에 붙이지 않는다)')
+})
+
+test('전량 교체 — 두 번 돌려도 늘지 않는다', async () => {
+  await projectStructure(domainId, INSTANCE, model(), SOURCE)
+  await projectStructure(domainId, INSTANCE, model(), SOURCE)
+  assert.equal(await ds.getRepository(TwinLocation).count(), 3)
+  assert.equal(await ds.getRepository(TwinEquipment).count(), 3)
+})
+
+test('원본에서 사라진 것은 행에서도 사라진다 — 캐시는 원본을 따라간다', async () => {
+  const shrunk = model()
+  shrunk.locations = shrunk.locations.filter(l => l.id !== 'weld-station')
+  shrunk.equipment = shrunk.equipment.filter(m => m.id !== 'welder-1')
+  await projectStructure(domainId, INSTANCE, shrunk, SOURCE)
+  assert.equal(await ds.getRepository(TwinLocation).count(), 2)
+  assert.equal(await ds.getRepository(TwinEquipment).count(), 2)
+  assert.equal(await ds.getRepository(TwinLocation).countBy({ locationId: 'weld-station' } as any), 0)
+})
+
+test('원본 표식 없는 행은 만들 수 없다 — 캐시라는 사실이 구조로 지켜진다', async () => {
+  await assert.rejects(
+    () =>
+      ds.getRepository(TwinLocation).save({
+        domain: { id: domainId },
+        locationId: 'no-origin',
+        type: 'storage'
+        /* sourceRef · ingestedAt 없음 */
+      } as any),
+    /NOT NULL|constraint/i,
+    '출처 없는 행이 들어가면 "원본에서 온 캐시" 라는 규율이 구조로는 안 지켜지는 것이다'
+  )
+})
+
+test('소요시간은 ISO 8601 문자열 그대로 — 분으로 접으면 초가 조용히 사라진다', async () => {
+  const op = await ds.getRepository(TwinOperation).findOne({ where: { operationKey: 'cut' } })
+  assert.equal(op?.duration, 'PT1H10M30S')
+  /* 변동성·파라미터는 도메인마다 형이 달라 원형 그대로 싣는다. */
+  assert.equal(op?.variability?.distribution, 'triangular')
+  assert.deepEqual(op?.parameters, [{ id: 'yield', value: '0.995' }])
+})
+
+test('등록되지 않은 트윈에는 투영하지 않는다 — 주인 없는 행을 만들지 않는다', async () => {
+  await assert.rejects(() => projectStructure(domainId, 'not-registered', model(), SOURCE), /not registered/)
+})
+
+test('네 자원 명세가 함께 옮겨진다 — 선언한 것만 제약이 되므로 빠지면 화면이 거짓이 된다', async () => {
+  /*
+   * ISA-95 는 공정이 무엇을 필요로 하는지를 넷으로 말한다: 설비·인원·자산·자재. 셋이 투영에서
+   * 떨어져 있어서, 조회 화면이 "원본이 말한 값" 이라 적고도 넷 중 하나만 보였다 — 사람이 필요한
+   * 공정을 보고 **사람이 필요 없다고 결론 내게** 되어 있었다.
+   */
+  const op = await ds.getRepository(TwinOperation).findOne({ where: { operationKey: 'cut' } })
+  assert.deepEqual(op?.personnelSpecification, [{ personnelClass: 'cutter-op', quantity: 1 }], '인원 명세가 행에 남아야 한다')
+  assert.deepEqual(op?.physicalAssetSpecification, [{ assetClass: 'jig', quantity: 1 }], '자산 명세도 남아야 한다')
+  assert.deepEqual(op?.materialSpecification, [{ materialDefinition: 'steel', use: 'consumed', quantity: 2 }], '자재 명세도 남아야 한다')
+})
+
+test('이름이 행까지 온다 — 이름이 없으면 화면에 id 만 남는다', async () => {
+  /*
+   * 투영이 마스터의 `name` 을 버리고 있었다. 행에 이름이 없으면 어떤 화면도 이름을 만들 수 없어서
+   * 목록·표·관계 그림이 모두 `cut-station` 을 찍었다 — 표면마다 따로 보이지만 결함은 여기 하나다.
+   */
+  const loc = await ds.getRepository(TwinLocation).findOne({ where: { domain: { id: domainId } as any, locationId: 'cut-station' } as any })
+  assert.equal(loc!.name, '프레임 절단', '자리의 이름이 행에 실려야 한다')
+
+  const eq = await ds.getRepository(TwinEquipment).findOne({ where: { domain: { id: domainId } as any, equipmentId: 'cutter-1' } as any })
+  assert.equal(eq!.name, '절단기 1호', '설비의 이름이 행에 실려야 한다')
+
+  /* 공정은 마스터가 `label` 로 말한다 — 행에서는 규약의 이름으로 둔다(어휘를 하나로). */
+  const op = await ds.getRepository(TwinOperation).findOne({ where: { domain: { id: domainId } as any, operationKey: 'cut' } as any })
+  assert.equal(op!.name, 'twin.tpl.x.cut', '공정의 이름이 행에 실려야 한다')
+
+  /* **이름 없는 원본은 이름 없이 남는다** — id 를 이름으로 베끼면 "이름이 있다" 는 거짓이 되고,
+     화면은 이름 없음을 알아볼 수 없게 된다. */
+  const noname = await ds.getRepository(TwinLocation).findOne({ where: { domain: { id: domainId } as any, locationId: 'weld-station' } as any })
+  assert.equal(noname!.name ?? null, null, '원본이 이름을 말하지 않았으면 비어 있어야 한다')
+})
+
+test('자원 속성이 행까지 온다 — 소비처가 실제로 읽는 사실이다(주행 속도)', async () => {
+  /*
+   * 모델에는 있는데 행에 자리가 없어 투영이 흘리고 있었다. 그러면 조회 화면은 "원본이 말한 값" 이라
+   * 적고도 속성을 못 보인다 — 이름이 같은 식으로 사라졌던 것과 같은 부류다.
+   *
+   * 단위를 값과 함께 담는지도 본다: 단위 없는 "1.2" 는 초속인지 시속인지 말하지 않는다.
+   */
+  const eq = await ds.getRepository(TwinEquipment).findOne({ where: { domain: { id: domainId } as any, equipmentId: 'cutter-1' } as any })
+  const props = (eq!.properties ?? []) as any[]
+  assert.equal(props.length, 1, '선언한 속성이 행에 실려야 한다')
+  assert.equal(props[0].id, 'speed')
+  assert.equal(props[0].value, '1.2')
+  assert.equal(props[0].uom, 'MTS', '단위가 값과 함께 남아야 한다')
+
+  /* 선언하지 않은 자원은 **비어 있다** — 빈 배열로 "선언했다" 고 말하지 않는다. */
+  const noneProps = await ds.getRepository(TwinEquipment).findOne({ where: { domain: { id: domainId } as any, equipmentId: 'welder-1' } as any })
+  assert.equal(noneProps!.properties ?? null, null)
+})

package/test/projection-reaches-screen.test.ts

@@ -0,0 +1,272 @@
+/*
+ * 선언 적합성(투영 편) — **모델이 말한 사실은 행에 남고, 행에 남은 것은 화면까지 간다.**
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 같은 이름의 하네스가 두 벌 있다. 커널 편은 *선언 ⊆ 상태* 를 지키고(kernel/declaration-in-state),
+ * 경계 편은 *원본 → 모델* 을 지킨다(declaration-reaches-model). 그런데 사실이 새던 구간은 **셋**이었고,
+ * 남은 하나가 이것이다: **모델 → DB 행 → 조회 응답.**
+ *
+ * 여기서 잃은 것들: 자리·설비의 이름(화면이 `cut-station` 을 찍었다) · GS1 참조 · 자원 속성 ·
+ * 시험 명세 참조 · 시험 결과. 전부 **투영 함수의 한 줄이 빠진** 것이었고, 그때는 사람이 하나씩 찾았다.
+ *
+ * 타입 검사는 못 잡는다: 컬럼이 거의 다 `nullable` 이라 **안 채우는 것이 합법**이다.
+ *
+ * ── 무엇이 기준인가 ─────────────────────────────────────────────────────────
+ * **엔티티의 컬럼**이다(TypeORM 메타데이터에서 실행 중에 읽는다 — 손으로 적지 않는다). 컬럼이 있다는
+ * 것은 "이 사실이 여기 앉는다" 는 선언이고, 앉을 자리를 만들어 두고 안 채우면 그 컬럼은 영원히 빈다.
+ *
+ * 그래서 컬럼마다 셋을 요구한다:
+ *   ① 픽스처가 모델에 그 값을 싣는다(값을 줄 방법을 모르면 **검사가 실패한다** — 조용히 건너뛰면
+ *      그 컬럼은 아무도 안 보는 컬럼이 된다)
+ *   ② 투영을 지나 행에 남는다
+ *   ③ 조회 응답에 나온다(화면이 읽는 자리)
+ *
+ * 기반 컬럼(id·관계·감사·출처)은 모델이 말하는 사실이 아니므로 이유와 함께 뺀다.
+ */
+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, getRepository } = 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 { TwinLocation } = req('../dist-server/service/twin-model/twin-location.js')
+const { TwinEquipment } = req('../dist-server/service/twin-model/twin-equipment.js')
+const { TwinOperation } = req('../dist-server/service/twin-model/twin-operation.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+let q: any
+let ctx: any
+
+const INSTANCE = 'projection-probe'
+
+/**
+ * 모델이 말하는 사실이 **아닌** 컬럼 — 이유와 함께.
+ *
+ * 비어 있으면 안 된다: 여기 적지 않으면 검사가 그 컬럼에 값을 요구하고, 그것은 틀린 요구다.
+ * 반대로 여기에 슬쩍 올리면 감시가 사라지므로 **이유를 함께 적는다**(리뷰가 볼 자리다).
+ */
+const NOT_FROM_MODEL: Record<string, string> = {
+  id: '행의 열쇠 — 모델이 정하지 않는다(DB 가 발급한다)',
+  locationId: '개체 식별자 — 대조의 열쇠라 값 비교에서 뺀다(존재는 조회로 이미 확인한다)',
+  equipmentId: '같음',
+  operationKey: '같음',
+  sourceRef: '어디서 왔나 — 투영이 남기는 근거다(모델의 사실이 아니라 옮긴 행위의 기록)',
+  ingestedAt: '언제 옮겼나 — 같은 이유',
+  seq: '문서의 차례 — 투영이 넣는 내부 컬럼이다(원본이 말한 값이 아니다)'
+}
+
+/** 컬럼별 값 — 이름으로 준다. 여기 없는 컬럼이 검사 대상에 들면 하네스가 실패한다. */
+const VALUE: Record<string, unknown> = {
+  name: '절단 스테이션',
+  description: '강판을 자르는 자리',
+  type: 'cut-station',
+  kind: 'cutter',
+  capacity: 40,
+  parallelism: 2,
+  level: 'WorkCenter',
+  gs1Id: 'urn:epc:id:sgln:0614141.00001.0',
+  homeLocation: 'cut-station',
+  mtbfMs: 600000,
+  mttrMs: 60000,
+  properties: [{ id: 'speed', value: '1.2', dataType: 'xs:double', uom: 'MTS' }],
+  testSpecificationIds: ['cut-cert'],
+  testResults: [{ specId: 'cut-cert', result: 'pass', expiresAt: '2099-01-01T00:00:00.000Z' }],
+  intent: 'process',
+  locationType: 'cut-station',
+  resourceType: 'cutter',
+  duration: 'PT25M',
+  variability: { distribution: 'triangular', min: 'PT20M', max: 'PT35M', mode: 'PT24M' },
+  parameters: [{ id: 'yield', value: '0.98' }],
+  personnelSpecification: [{ personnelClass: 'cutter-op', quantity: 1 }],
+  equipmentSpecification: [{ equipmentClass: 'cutter', quantity: 1 }],
+  physicalAssetSpecification: [{ assetClass: 'euro-pallet', quantity: 1 }],
+  materialSpecification: [{ material: 'steel', quantity: 1 }],
+  label: '프레임 절단'
+}
+
+interface Case {
+  axis: 'locations' | 'equipment' | 'operations'
+  entity: any
+  /** 행에서 그 개체를 찾는 컬럼 — 조회가 쓰는 것과 같은 이름이어야 한다(§ROW_BACKED). */
+  idColumn: string
+  id: string
+}
+
+const CASES: Case[] = [
+  { axis: 'locations', entity: TwinLocation, idColumn: 'locationId', id: 'cut-station' },
+  { axis: 'equipment', entity: TwinEquipment, idColumn: 'equipmentId', id: 'cutter-1' },
+  { axis: 'operations', entity: TwinOperation, idColumn: 'operationKey', id: 'cut' }
+]
+
+/**
+ * 그 엔티티에서 **모델이 채워야 하는 컬럼** — TypeORM 메타데이터에서 읽는다(손으로 적지 않는다).
+ * 관계·관계 id·감사 컬럼은 기반이므로 뺀다(그 판정은 조회가 쓰는 규칙과 같은 근거를 쓴다).
+ */
+function watchedColumns(entity: any): string[] {
+  const meta = getRepository(entity).metadata
+  const infra = new Set<string>(['createdAt', 'updatedAt', 'creator', 'updater', 'creatorId', 'updaterId'])
+  for (const rel of meta.relations) {
+    infra.add(rel.propertyName)
+    for (const jc of rel.joinColumns) infra.add(jc.propertyName)
+  }
+  for (const rid of meta.relationIds) infra.add(rid.propertyName)
+  return meta.columns
+    .map((c: any) => c.propertyName as string)
+    .filter((n: string) => !infra.has(n) && !(n in NOT_FROM_MODEL))
+    .sort()
+}
+
+/** 모든 감시 컬럼에 값을 실은 마스터. */
+function master(): any {
+  const fill = (c: Case): Record<string, unknown> => {
+    const o: Record<string, unknown> = {}
+    for (const col of watchedColumns(c.entity)) {
+      assert.ok(
+        col in VALUE,
+        `픽스처가 "${c.axis}.${col}" 에 실을 값을 모른다 — VALUE 에 하나 적어라(모델의 사실이 아니면 NOT_FROM_MODEL 에 이유와 함께).\n` +
+          '조용히 건너뛰면 그 컬럼은 아무도 안 보는 컬럼이 되고, 그것이 이 하네스가 막으려는 실패다.'
+      )
+      o[col] = VALUE[col]
+    }
+    return o
+  }
+  const loc = fill(CASES[0])
+  const eq = fill(CASES[1])
+  const op = fill(CASES[2])
+  return {
+    source: INSTANCE,
+    system: 'mes',
+    siteName: '투영 공장',
+    space: { spaceId: 'projection-site', width: 60, depth: 40, unit: 'm' },
+    locations: [
+      { id: CASES[0].id, role: 'location', ...loc },
+      { id: 'fg-store', type: 'fg-store', role: 'location', name: '완제품', capacity: 100 }
+    ],
+    /* 경계에서 이름이 바뀌는 것은 하나다(`homeLocationId → homeLocation`) — 경계 편 하네스가 지킨다. */
+    equipment: [{ id: CASES[1].id, ...eq, homeLocationId: CASES[0].id }],
+    testSpecifications: [{ id: 'cut-cert', name: '절단 자격' }],
+    personnelClasses: [{ id: 'cutter-op', description: 'twin.tpl.test.class.cutter-op' }],
+    assetClasses: [{ id: 'euro-pallet' }],
+    operations: [{ key: CASES[2].id, ...op }],
+    productionSpec: {
+      companyPrefix: '0614141',
+      binding: { steel: '077101' },
+      definition: {
+        materials: [{ id: 'steel' }],
+        routes: [{ key: 'r', steps: [CASES[2].id] }],
+        recipes: [{ key: 'rc', label: '프레임', route: 'r', inputs: [{ material: 'steel', qty: 1 }], outputs: [{ material: 'steel', qty: 1 }] }]
+      }
+    }
+  }
+}
+
+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: 'projection-test', subdomain: 'projection-test' } as any)
+  domainId = d.id
+  q = new TwinModelItemQuery()
+  ctx = { state: { domain: { id: domainId } } }
+
+  await TwinEngine.ingestMaster(domainId, master())
+})
+
+after(async () => {
+  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('감시할 컬럼이 비어 있지 않다 — 비면 이 하네스는 아무것도 지키지 않는다', () => {
+  for (const c of CASES) {
+    const cols = watchedColumns(c.entity)
+    assert.ok(cols.length > 2, `${c.axis}: 감시 컬럼을 못 읽었다(${cols.length}개) — 메타데이터 읽기가 낡았다`)
+  }
+})
+
+for (const c of CASES) {
+  test(`${c.axis}: 모델이 말한 사실이 행에 남는다 — 투영이 버리지 않는다`, async () => {
+    const row: any = await getRepository(c.entity).findOne({
+      where: { domain: { id: domainId } as any, [c.idColumn]: c.id } as any
+    })
+    assert.ok(row, `${c.axis} "${c.id}" 행이 없다 — 사실 하나가 아니라 개체가 사라졌다`)
+
+    const lost = watchedColumns(c.entity).filter(col => row[col] === null || row[col] === undefined)
+    assert.deepEqual(
+      lost,
+      [],
+      `${c.axis}: 모델은 말했는데 행에 없는 사실 [${lost}] — 투영이 버렸다.\n` +
+        '컬럼이 있다는 것은 "이 사실이 여기 앉는다" 는 선언이다 — 앉을 자리를 두고 안 채우면 영원히 빈다.'
+    )
+  })
+
+  test(`${c.axis}: 행에 남은 사실이 화면까지 간다 — 조회가 감추지 않는다`, async () => {
+    const it = await q.twinModelItem(INSTANCE, c.axis, c.id, ctx)
+    assert.ok(it?.declared, `${c.axis} "${c.id}" 항목이 열리지 않았다`)
+    assert.equal(it.provenance?.basis, 'rows', '행에서 답해야 이 검사가 그 구간을 지킨다')
+
+    const hidden = watchedColumns(c.entity).filter(col => it.declared[col] === undefined)
+    assert.deepEqual(
+      hidden,
+      [],
+      `${c.axis}: 행에는 있는데 조회 응답에 없는 사실 [${hidden}] — 화면은 그것을 물을 방법이 없다.`
+    )
+  })
+}
+
+/*
+ * ★ 어떤 속성이 **효과가 있나** — 열린 것과 닫힌 것을 화면이 구별할 수 있게.
+ *
+ * 속성은 열려 있다(아무 사실이나 실어 보낼 수 있다). 그런데 값이 계산을 바꾸려면 그 규칙을 코드가
+ * 알아야 하고, 그것은 닫혀 있다. 그 구분이 화면에 없으면 사용자는 속성을 넣고 나서 **아무 일도 안
+ * 일어나는 이유**를 알 수 없다. 그래서 서버가 효과 등록부를 함께 낸다.
+ *
+ * 이 검사가 지키는 규율: **읽는 코드가 있는 것만 등록한다.** 지어낸 효과를 올리면 화면이 거짓을 말한다.
+ */
+test('설비 항목이 효과 등록부를 함께 낸다 — 속도는 효과가 있고 나머지는 표시뿐이다', async () => {
+  const it = await q.twinModelItem(INSTANCE, 'equipment', 'cutter-1', ctx)
+  assert.ok(it?.propertyEffects, '등록부가 없으면 화면은 효과 있는 속성을 구별할 수 없다')
+  assert.equal(it.propertyEffects.speed, 'twin.propeffect.speed', '속도는 주행 시간 계산이 읽는다')
+  assert.equal('maxLoadKg' in it.propertyEffects, false, '읽는 코드가 없는 속성을 등록하면 화면이 거짓을 말한다')
+})
+
+test('등록부의 모든 항목이 읽는 자리를 밝힌다 — 지어낸 효과를 막는다', () => {
+  const { PROPERTY_EFFECTS } = req('../dist-server/engine/property-effects.js')
+  assert.ok(PROPERTY_EFFECTS.length > 0, '등록부가 비면 아무것도 지키지 않는다')
+  for (const e of PROPERTY_EFFECTS) {
+    assert.ok(e.id && e.axes?.length, `${e.id}: 어느 축의 속성인지 밝혀야 한다`)
+    assert.match(e.effect, /^twin\.propeffect\./, `${e.id}: 효과 문구는 i18n 키다(서버는 사람 말을 만들지 않는다)`)
+    assert.ok(e.readBy && e.readBy.length > 10, `${e.id}: 실제로 읽는 자리를 적어야 한다 — 없으면 지어낸 효과다`)
+  }
+})
+
+test('등록되지 않은 속성은 등록부에 없다 — 화면이 "표시만 됩니다" 를 말할 근거가 된다', () => {
+  const { propertyEffectsOf } = req('../dist-server/engine/property-effects.js')
+  const eq = propertyEffectsOf('equipment')
+  /*
+   * 지금 트레일러 템플릿에는 효과 없는 속성이 선언돼 있지 않다(속도 하나뿐이다). 그래서 화면에서
+   * "표시만 됩니다" 를 눈으로 볼 수 없다 — 그 갈래를 여기서 지킨다: 등록부에 없으면 화면이 그렇게 말한다.
+   */
+  assert.equal(eq.speed, 'twin.propeffect.speed')
+  for (const unknown of ['maxLoadKg', 'skill', 'nominalSpeed']) {
+    assert.equal(unknown in eq, false, `읽는 코드가 없는 "${unknown}" 이 등록되면 화면이 거짓을 말한다`)
+  }
+  /* 축이 다르면 효과도 다르다 — 품목 정의의 환산 계수를 설비에 말하지 않는다. */
+  assert.equal('perBaseUnit' in eq, false)
+  assert.equal(propertyEffectsOf('materialDefinitions').perBaseUnit, 'twin.propeffect.perBaseUnit')
+})

package/test/property-effects.test.ts

@@ -0,0 +1,96 @@
+/*
+ * 속성 효과 등록부 — **지어낸 효과를 등록하지 않고, 있는 효과를 숨기지 않는다.**
+ *
+ * ── 왜 이 시험이 있나 (2026-08-18) ──────────────────────────────────────────
+ * 화면은 속성마다 「무엇을 바꾸나」를 말한다. 등록되지 않은 속성에는 「표시만 됩니다」라고 한다 — 그것이
+ * 정직한 기본값이다. 그런데 에너지 값들(계약전력·정격·요금)은 **오래전부터 읽히고 있었는데** 등록부에
+ * 없었다: 사용자는 계약전력을 넣고도 「이 값은 아무것도 바꾸지 않는다」는 문장을 읽었다. 조용한 거짓말이다.
+ *
+ * 반대 방향의 위험도 있다: 효과를 등록해 두고 **읽는 코드가 없으면** 화면이 「쓰입니다」라고 말하는데
+ * 아무 일도 일어나지 않는다. 그래서 등록부의 각 줄이 가리키는 자리를 이 시험이 확인한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+import { PROPERTY_EFFECTS, propertyEffectsOf, declarationTargetsOf } from '../server/engine/property-effects.ts'
+
+const req = createRequire(import.meta.url)
+/*
+ * 커널은 **한 벌로 묶인 산출물**을 내보낸다(`dist-cjs/index.cjs`) — 서브패스는 exports 로 막혀 있다.
+ * 그래서 모듈마다 읽지 않고 그 묶음 하나를 읽는다(안에 커널의 모든 읽기 코드가 들어 있다).
+ */
+const kernelBundle = readFileSync(req.resolve('@operato/twin-kernel'), 'utf-8')
+const hostSrc = (file: string): string => readFileSync(fileURLToPath(new URL(`../server/${file}`, import.meta.url)), 'utf-8')
+
+test('등록부의 모든 줄이 자기 자리를 가리킨다 — 빈 항목이 없다', () => {
+  for (const e of PROPERTY_EFFECTS) {
+    assert.ok(e.id, '속성 id 가 있어야 한다')
+    assert.ok(e.axes.length, `${e.id}: 어느 축의 속성인지 말해야 한다`)
+    assert.match(e.effect, /^twin\.propeffect\./, `${e.id}: 효과 문장은 i18n 키다(서버는 사람 말을 만들지 않는다)`)
+    assert.ok(e.readBy && e.readBy.length > 10, `${e.id}: 실제로 읽는 자리를 적어야 한다`)
+  }
+})
+
+test('등록한 속성 id 를 읽는 코드가 실제로 있다 — 「쓰입니다」가 거짓이 되지 않게', () => {
+  /* 읽는 쪽 소스 — 커널(에너지·환산·주행)과 호스트(요금·주행 추정). */
+  const corpus = [kernelBundle, hostSrc('engine/kpi-query.ts'), hostSrc('engine/travel-estimator.ts')].join('\n')
+
+  const missing: string[] = []
+  for (const e of PROPERTY_EFFECTS) {
+    /* id 그대로 나오거나(문자열 리터럴), 커널 어휘 상수의 마지막 마디로 나온다(EMS_PROPERTY.contractKW). */
+    const tail = e.id.includes('.') ? e.id.split('.').pop()! : e.id
+    if (!corpus.includes(`'${e.id}'`) && !corpus.includes(`"${e.id}"`) && !new RegExp(`\\b${tail}\\b`).test(corpus)) missing.push(e.id)
+  }
+  assert.deepEqual(missing, [], `읽는 코드를 찾지 못한 등록 항목:\n${missing.join('\n')}`)
+})
+
+test('에너지 값들이 등록돼 있다 — 예전에는 「표시만 됩니다」라고 말했다', () => {
+  const ids = PROPERTY_EFFECTS.map(e => e.id)
+  for (const id of ['contract.kW', 'power.ratedKW', 'storage.capacityKWh', 'tariff.demandChargePerKW', 'tariff.currency'])
+    assert.ok(ids.includes(id), `${id} 가 등록부에 없다`)
+})
+
+test('축으로 갈라 낸다 — 그 축의 항목에만 효과를 말한다', () => {
+  const locations = propertyEffectsOf('locations')
+  const equipment = propertyEffectsOf('equipment')
+  assert.ok(locations['contract.kW'], '계약전력은 자리의 속성이다')
+  assert.equal(locations['power.ratedKW'], undefined, '설비 속성을 자리에 말하지 않는다')
+  assert.ok(equipment['speed'], '속도는 설비의 속성이다')
+  assert.equal(equipment['tariff.currency'], undefined, '요금은 자리(수전)의 속성이다')
+})
+
+test('요금은 커널이 아니라 호스트가 읽는다 — 그 사실을 readBy 가 말한다', () => {
+  const tariff = PROPERTY_EFFECTS.filter(e => e.id.startsWith('tariff.'))
+  assert.equal(tariff.length, 3)
+  for (const e of tariff) assert.match(e.readBy, /kpi-query/, '금액은 저널을 접는 쪽이 만든다')
+})
+
+/*
+ * ── 어느 대상에 얹히나 (2026-08-18) ────────────────────────────────────────
+ * 지게차에 계약전력을 선언할 수 있었다 — 문은 받고 화면은 「넣었습니다」라고 말하는데, 읽는 코드는
+ * 자리(수전)만 본다. 그 제한은 이미 등록부의 축이 알고 있으므로, 검사에 그 지식을 쓴다(두 곳에 적지
+ * 않는다). 등록부에 없는 속성은 **제한을 모르는 것**이므로 받아 준다 — 속성은 열려 있고 효과만 닫혀 있다.
+ */
+test('축이 곧 얹을 수 있는 대상이다 — 목록을 따로 적지 않는다', () => {
+  assert.deepEqual(declarationTargetsOf('contract.kW'), ['location'])
+  assert.deepEqual(declarationTargetsOf('speed'), ['equipment'])
+  assert.deepEqual(declarationTargetsOf('operation.duration'), ['operation'])
+  /* 선언 대상이 아닌 축(자재 정의)은 제한을 말하지 않는다 — 이 문의 대상이 아니다. */
+  assert.equal(declarationTargetsOf('perBaseUnit'), undefined)
+  assert.equal(declarationTargetsOf('made.up.property'), undefined, '모르는 속성은 제한도 모른다')
+})
+
+test('공정 시간이 등록돼 있고, 그 값을 실어 보내는 자리를 가리킨다', () => {
+  const e = PROPERTY_EFFECTS.find(x => x.id === 'operation.duration')!
+  assert.ok(e, '공정 시간이 등록부에 있어야 한다')
+  assert.deepEqual(e.axes, ['operations'])
+  assert.match(e.readBy, /declareDurations/, '커널의 어느 창구로 가는지 말한다')
+  /* 실어 보내는 코드가 실제로 있다 — 등록만 해 두고 아무도 나르지 않으면 화면이 거짓을 말한다. */
+  const layer = hostSrc('engine/local-declarations.ts')
+  assert.match(layer, /OPERATION_PROPERTY\.duration/, '선언 겹이 그 속성을 안다')
+  assert.match(layer, /isoDurationOf/, '커널이 읽는 표기로 바꾼다')
+  assert.match(hostSrc('engine/twin-engine.ts'), /declareDurations\(declared\)/, '기동·구조전환 때 커널에 싣는다')
+})