@things-factory/headless-twin 10.0.11 → 10.0.12

package/test/operational-vocabulary.test.ts

@@ -0,0 +1,108 @@
+/*
+ * **라이브 문이 운영 사실을 안다** — 미러가 시뮬보다 가난하지 않게 (ADR-0029 어휘 넓히기, 2026-08-19).
+ *
+ * ── 무엇이 막혀 있었나 ──────────────────────────────────────────────────────
+ * 이 문(`ingestCanonicalRecords`)은 어휘를 셋만 알았다: EPCIS 품목 · 에너지 계량 · 설비 에너지. 그리고
+ * **모르는 것은 EPCIS 로 떨어졌다** — 작업 사실을 넣으면 `epc` 가 없어 거부됐고, 원본은 「이 작업이
+ * 끝났다」를 말할 길이 없었다. 시뮬 커널만 그것을 알고 미러는 영원히 몰랐다.
+ *
+ * ── 이 시험이 지키는 것 ─────────────────────────────────────────────────────
+ *  ① 네 어휘가 **한 문**에서 갈린다(판정은 커널의 것이고 여기서 다시 짐작하지 않는다).
+ *  ② 운영 사실이 자기 봉투로 나온다 — EPCIS 로 감싸지지 않는다.
+ *  ③ 섞여 와도 갈린다(실 피드는 한 배치에 여러 어휘가 섞인다).
+ *  ④ 거부는 이유와 함께 남는다 — 피드 결선이 그 이유를 사람에게 말한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { ingestCanonicalRecords } from '../server/engine/canonical-ingest.ts'
+
+const AT = '2026-08-19T09:00:00.000Z'
+
+test('운영 사실이 자기 봉투로 나온다 — EPCIS 로 감싸지지 않는다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [{ taskId: 'tk-1', kind: 'putaway', status: 'completed' } as any],
+    'domain-1',
+    AT
+  )
+  assert.deepEqual(rejected, [])
+  assert.equal(accepted.length, 1)
+  assert.equal(accepted[0].eventType, 'task.status')
+  assert.equal(accepted[0].eventTime, AT, '시각을 주지 않으면 이 문이 정한 기본 시각을 쓴다')
+  assert.equal(accepted[0].tenantId, 'domain-1')
+})
+
+test('네 어휘가 한 배치에서 갈린다 — 실 피드는 섞여 온다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [
+      { epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
+      { meterId: 'm-1', kW: 120 },
+      { equipmentId: 'pv-1', generatedKW: 40 },
+      { moverId: 'fk-1', kind: 'forklift', status: 'busy' }, // vocabulary-guard: allow 저널 와이어 필드
+      { orderId: 'or-1', kind: 'outbound', status: 'picking', requested: 10, fulfilled: 3 }
+    ] as any,
+    'domain-1',
+    AT
+  )
+  assert.deepEqual(rejected, [], '어느 어휘도 남의 길로 떨어지지 않는다')
+  assert.deepEqual(accepted.map(e => e.eventType).sort(), [
+    'energy.equipment', 'energy.measured', 'epcis.ObjectEvent', 'equipment.status', 'order.status'
+  ].sort())
+})
+
+test('거부는 이유와 함께 남는다 — 유효한 것은 함께 통과한다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [
+      { taskId: 'tk-1', kind: 'pick', status: 'completed' },
+      { taskId: 'tk-2', kind: 'pick', status: 'FINISHED' } // 커널이 접을 수 없는 낱말
+    ] as any,
+    'domain-1',
+    AT
+  )
+  assert.equal(accepted.length, 1)
+  assert.equal(rejected.length, 1)
+  assert.ok(rejected[0].errors.join(' ').length > 0)
+})
+
+test('피드 결선이 거부를 조용히 버리지 않는다 — 이유를 사람에게 말한다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/reference/reference-live.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /record\(s\) rejected/, '거부 수와 이유를 남긴다')
+})
+
+/*
+ * ── 담김도 이 문을 지난다 (2026-08-19) ──────────────────────────────────────
+ * 실 앱에서 한 바퀴 돌리자 「옮기지 못했다」 로그가 `epcis.AggregationEvent` 를 짚었다 — 관측 리듀서는 그
+ * 사실로 자식 물품에 `parent` 를 붙이는데(3D 가 「이 상자가 어느 팔레트에 실렸나」를 묻는 자리) 문에 그
+ * 어휘가 없었다.
+ */
+test('담김 레코드가 자기 봉투로 나온다 — 개체 관측과 한 배치에 섞여 와도 갈린다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [
+      { epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
+      { parentID: 'urn:epc:id:sscc:0614141.0000000001', childEPCs: ['urn:epc:id:sgtin:1.1.1'], action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:packing', readPoint: 'packing' }
+    ] as any,
+    'domain-1',
+    AT
+  )
+  assert.deepEqual(rejected, [])
+  assert.deepEqual(accepted.map(e => e.eventType), ['epcis.ObjectEvent', 'epcis.AggregationEvent'])
+  assert.equal((accepted[1].data as any).parentID, 'urn:epc:id:sscc:0614141.0000000001')
+})
+
+test('자리를 구조째 실으면 거부한다 — 예전에는 "[object Object]" 로 굳어 저널에 쌓였다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [{ epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: { id: 'dock-1' } }] as any,
+    'domain-1',
+    AT
+  )
+  assert.equal(accepted.length, 0)
+  assert.match(rejected[0].errors.join(' '), /readPoint/)
+})
+
+test('이 문이 어휘가 넷임을 스스로 말한다 — 다음 사람이 세 어휘로 읽지 않게', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/engine/canonical-ingest.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /어휘가 넷이다/)
+  assert.match(src, /isOperationalRecord/, '판정은 커널의 것을 부른다(여기서 다시 짐작하지 않는다)')
+})

package/test/operations-capability-db.test.ts

@@ -102,8 +102,8 @@ before(async () => {
   q = new TwinJournalQuery()
   ctx = { state: { domain: { id: domainId } } }
 
-  await TwinEngine.ingestMaster(domainId, mesMaster())
-  await TwinEngine.ingestMaster(domainId, wmsMaster())
+  await TwinEngine.ingestMaster(domainId, mesMaster(), 'reset')
+  await TwinEngine.ingestMaster(domainId, wmsMaster(), 'reset')
 })
 
 after(async () => {
@@ -122,7 +122,7 @@ test('실행 중이 아니면 그 사실을 알린다 — "없는 것" 과 구
 })
 
 test('돌고 있으면 구간의 양을 종류로 갈라 낸다 — 표준 등식이 성립한다', async () => {
-  await TwinEngine.startFromRegistry(domainId, MES, 'sim-experiment')
+  await TwinEngine.startFromRegistry(domainId, MES, 'reset')
   const rows = await ask(MES)
   assert.equal(rows[0].reason, undefined)
 
@@ -138,7 +138,7 @@ test('돌고 있으면 구간의 양을 종류로 갈라 낸다 — 표준 등
 })
 
 test('공정을 선언하지 않은 트윈은 판정 대상이 아니다 — 0 으로 채우면 없는 병목이 생긴다', async () => {
-  await TwinEngine.startFromRegistry(domainId, WMS, 'sim-experiment')
+  await TwinEngine.startFromRegistry(domainId, WMS, 'reset')
   const rows = await q.twinOperationsCapability(WMS, undefined, 24, WINDOW.fromTime, WINDOW.toTime, WINDOW.fromTime, ctx)
   assert.equal(rows[0].reason, 'no-operations')
   assert.equal(rows[0].report, undefined)

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

@@ -81,7 +81,7 @@ before(async () => {
     domain: { id: domainId },
     instanceId: INSTANCE,
     kind: 'mes',
-    realityMode: 'sim-experiment',
+    restartPolicy: 'reset',
     purpose: 'operational',
     status: 'stopped',
     model: {}

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

@@ -184,7 +184,7 @@ before(async () => {
   q = new TwinModelItemQuery()
   ctx = { state: { domain: { id: domainId } } }
 
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 after(async () => {

package/test/property-effects.test.ts

@@ -94,3 +94,31 @@ test('공정 시간이 등록돼 있고, 그 값을 실어 보내는 자리를
   assert.match(layer, /isoDurationOf/, '커널이 읽는 표기로 바꾼다')
   assert.match(hostSrc('engine/twin-engine.ts'), /declareDurations\(declared\)/, '기동·구조전환 때 커널에 싣는다')
 })
+
+/*
+ * 모수도 같은 배선을 지난다 (2026-08-19).
+ *
+ * 이 시험이 소스를 보는 이유: 모수를 읽는 순간은 **작업이 완료될 때**라서 실 앱에서 관측하려면 라인이
+ * 한 바퀴 돌아야 한다(복원된 25분 작업이 쌓인 트윈에서는 그 관측이 오래 걸린다 — 실제로 그랬다).
+ * 값이 커널까지 가는 **경로**는 여기서 지키고, 커널이 그 값을 쓰는지는 커널 시험이 값으로 지킨다.
+ */
+test('수율·셋업이 커널 창구까지 배선돼 있다 — 등록만 하고 나르지 않으면 화면이 거짓을 말한다', () => {
+  const layer = hostSrc('engine/local-declarations.ts')
+  assert.match(layer, /OPERATION_PROPERTY\.yield/, '선언 겹이 수율을 안다')
+  assert.match(layer, /OPERATION_PROPERTY\.setupDuration/, '선언 겹이 셋업을 안다')
+  /* 퍼센트 → 비율 환산은 **한 곳**이어야 한다(두 곳이면 100 이 두 번 걸린다). */
+  const divisions = layer.match(/pct \/ 100/g) ?? []
+  assert.equal(divisions.length, 1, `퍼센트 환산은 한 자리에서만 (발견 ${divisions.length})`)
+  assert.match(hostSrc('engine/twin-engine.ts'), /declareParameters\(params\)/, '기동·구조전환 때 커널에 싣는다')
+  /* 커널이 그 창구를 갖지 않은 버전이면 **말한다** — 조용히 상수로 돌지 않게. */
+  assert.match(hostSrc('engine/twin-engine.ts'), /declareParameters missing/, '버전 어긋남을 경고로 드러낸다')
+})
+
+test('공정 모수가 등록부에 있고 읽는 자리를 가리킨다', () => {
+  for (const id of ['operation.yield', 'operation.setupDuration']) {
+    const e = PROPERTY_EFFECTS.find(x => x.id === id)!
+    assert.ok(e, `${id} 가 등록부에 있어야 한다`)
+    assert.deepEqual(e.axes, ['operations'])
+    assert.match(e.readBy, /declareParameters/, '어느 창구로 가는지 말한다')
+  }
+})

package/test/restart-policy.test.ts

@@ -0,0 +1,111 @@
+/*
+ * **재기동 정책** — 개명(ADR-0029 §2)과 그 규율 둘.
+ *
+ * ── 무엇을 바꿨나 ───────────────────────────────────────────────────────────
+ * `realityMode`(`mirror`·`sim-world`·`sim-experiment`) → `restartPolicy`(`resync`·`resume`·`reset`).
+ * 「현실이 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이고, 코드가 이 축으로 실제로 가른 것은
+ * **재기동 거동 하나**였다 — 그것은 원본의 성질이 아니라 트윈과 자기 과거의 관계다. 그래서 축은 남고
+ * 이름이 바뀌었다.
+ *
+ * ── 지키는 규율 둘 (계획서 §6) ──────────────────────────────────────────────
+ * ① **모르는 값은 던진다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다 — 값이
+ *    하나 어긋나는 순간 이력을 지우는 길이다. 기본값을 없앴다.
+ * ② **옛 어휘를 번역하지 않는다.** 번역을 두면 옛 값이 살아남고 다시 저장된다. 저장된 값은 한 번
+ *    옮기고(데이터 이관), 코드는 새 어휘만 안다 — 다만 무엇으로 옮겨야 하는지는 오류 문장이 말한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+import { readRestartPolicy, isRestartPolicy, RESTART_POLICIES } from '../server/engine/restart-policy.ts'
+
+test('셋뿐이다 — 그리고 그 셋을 읽는다', () => {
+  assert.deepEqual([...RESTART_POLICIES], ['resync', 'resume', 'reset'])
+  for (const p of RESTART_POLICIES) assert.equal(readRestartPolicy(p, 'test'), p)
+  assert.equal(readRestartPolicy('  resume  ', 'test'), 'resume', '공백은 다듬는다')
+})
+
+test('미선언은 던진다 — 기본값으로 메우면 저널이 지워지는 길이 열린다', () => {
+  for (const raw of [undefined, null, '', '   ', 42, {}]) {
+    assert.throws(() => readRestartPolicy(raw, 'twin "x"'), /twin "x": restart policy/)
+  }
+  /* 무엇을 해야 하는지 문장이 말한다 — 코드를 그대로 던지지 않는다. */
+  try {
+    readRestartPolicy(undefined, 'twin "x"')
+    assert.fail('던져야 한다')
+  } catch (e: any) {
+    assert.match(e.message, /resync \| resume \| reset/)
+    assert.match(e.message, /no default/)
+  }
+})
+
+test('옛 어휘도 던진다 — 다만 무엇으로 옮길지 말한다(번역해 주지 않는다)', () => {
+  const cases: [string, string][] = [
+    ['mirror', 'resync'],
+    ['sim-world', 'resume'],
+    ['sim-experiment', 'reset']
+  ]
+  for (const [old, next] of cases) {
+    try {
+      readRestartPolicy(old, 'twin "x"')
+      assert.fail(`${old} 은 던져야 한다`)
+    } catch (e: any) {
+      assert.match(e.message, /old vocabulary/)
+      assert.match(e.message, new RegExp(`"${next}"`), '옮길 값을 말한다')
+    }
+  }
+})
+
+test('묻는 자리도 있다 — 화면·검사는 던지지 않고 판별한다', () => {
+  assert.equal(isRestartPolicy('resume'), true)
+  assert.equal(isRestartPolicy('sim-world'), false)
+  assert.equal(isRestartPolicy(undefined), false)
+})
+
+/*
+ * ── 옛 어휘가 코드로 되돌아오지 않게 (계획서 §6 의 검사) ────────────────────
+ * ADR-0034 의 `local-declarations.test.ts` 가 `site*` 에 대해 하는 것과 같은 방식이다. 개명은 저장값·타입·
+ * 화면에 걸쳐 있어서, 한 곳만 되돌아와도 그 자리가 조용히 다르게 재기동한다.
+ */
+const OLD_TOKENS = [/\brealityMode\b/, /\bRealityMode\b/, /'sim-world'/, /'sim-experiment'/, /DEFAULT_REALITY_MODE/]
+
+function sources(root: string): { file: string; src: string }[] {
+  const base = fileURLToPath(new URL(root, import.meta.url))
+  const out: { file: string; src: string }[] = []
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      if (name === 'node_modules' || name.startsWith('dist')) continue
+      const path = join(dir, name)
+      if (statSync(path).isDirectory()) { walk(path); continue }
+      if (name.endsWith('.ts')) out.push({ file: path.slice(base.length + 1), src: readFileSync(path, 'utf-8') })
+    }
+  }
+  walk(base)
+  return out
+}
+
+test('옛 어휘가 코드에 없다 — 이력을 설명하는 주석만 예외다', () => {
+  const offenders: string[] = []
+  for (const { file, src } of [...sources('../server'), ...sources('../test')]) {
+    /* 이력 설명(「예전에는 …」)과 이관 안내(restart-policy.ts)는 남아야 한다 — 그것이 개명의 근거다. */
+    if (file.endsWith('restart-policy.ts') || file.endsWith('restart-policy.test.ts')) continue
+    for (const line of src.split('\n')) {
+      const isComment = /^\s*(\*|\/\/|\/\*)/.test(line)
+      if (isComment) continue
+      if (OLD_TOKENS.some(re => re.test(line))) offenders.push(`${file}: ${line.trim().slice(0, 80)}`)
+    }
+  }
+  assert.deepEqual(offenders, [], `옛 어휘가 코드로 돌아왔다:\n${offenders.join('\n')}`)
+})
+
+test('기본값 상수가 없다 — 미선언을 우리가 고르지 않는다', () => {
+  const engine = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+  const code = engine
+    .split('\n')
+    .filter(line => !/^\s*(\*|\/\/|\/\*)/.test(line))
+    .join('\n')
+  assert.equal(/DEFAULT_RESTART_POLICY/.test(code), false, '기본값 상수가 되살아나면 미선언이 다시 조용해진다')
+  assert.match(code, /readRestartPolicy\(/, '읽는 자리는 엄격한 리더를 지난다')
+})

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

@@ -73,5 +73,11 @@ test('프로비저닝이 고른 현장을 origin 에 남기고, 다시 읽기가
     .join('\n')
   assert.match(code, /kind: 'template', templateId, params: effective, \.\.\.\(spaceId \? \{ spaceId \} : \{\}\)/, '템플릿 트윈이 현장을 기억한다')
   assert.match(code, /const keepSpace = origin\.spaceId \|\| inst\.spaceId/, '기억이 없으면 지금 있는 현장을 지킨다')
-  assert.match(code, /ingestMaster\(domainId, master, keepSpace \? \{ spaceId: keepSpace \} : undefined/, '다시 읽기가 그 현장으로 넣는다')
+  /* 인자 사이에 재기동 정책이 끼었다(ADR-0029 §2) — 현장을 넘기는 인자는 그대로여야 한다. */
+  assert.match(code, /keepSpace \? \{ spaceId: keepSpace \} : undefined/, '다시 읽기가 그 현장으로 넣는다')
+  assert.match(
+    code,
+    /readRestartPolicy\(inst\.restartPolicy, `resync of twin/,
+    '다시 읽기는 그 트윈의 정책을 그대로 지킨다(구조만 새로 그린다)'
+  )
 })

package/test/source-outcome-audit.test.ts

@@ -0,0 +1,104 @@
+/*
+ * **허락과 일어남 사이를 같은 행에 닫는다** — ADR-0029 §1 결정 C (2026-08-19).
+ *
+ * ── 무엇이 열려 있었나 ──────────────────────────────────────────────────────
+ * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다: 어댑터가 조용히 실패하면 원장에는 승인만 남는다.
+ * 그리고 구동 문(`controlTwinSource`)은 감사를 **아예 남기지 않았다** — 자극을 바꾸고 배속을 올리는 것은
+ * 그 트윈의 사실을 바꾸는 행위인데, 나중에 「무엇이 이 공장을 흔들었나」에 답할 수 없었다.
+ *
+ * ── 세 값을 구별한다 ────────────────────────────────────────────────────────
+ *  · 칸이 **없음** — 원본에 묻지 않았다(커널이 받은 명령).
+ *  · `unknown` — 물었는데 답이 없다. **성공으로 적지 않는다.**
+ *  · `applied`·`refused` — 원본이 답했다(둘 다 사실이다).
+ *
+ * 셋을 뭉개면 둘 중 하나가 된다: 일어난 일을 없던 일로 만들거나, 없던 일을 일어난 일로 만든다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { buildCommandAudit, sourceOutcomeOf } from '../server/service/twin-audit/command-audit.ts'
+
+const at = new Date('2026-08-19T05:00:00.000Z')
+
+test('묻지 않았으면 칸을 만들지 않는다 — 커널이 받은 명령이 그렇다', () => {
+  const row = buildCommandAudit({ command: { type: 'order.hold', origin: 'user' }, ack: { accepted: true }, at })
+  assert.equal('sourceOutcome' in row, false, '없음은 「모른다」가 아니라 「묻지 않았다」다')
+  assert.equal('sourceCode' in row, false)
+})
+
+test('물었는데 답이 없으면 unknown — 성공으로 적지 않는다', () => {
+  const row = buildCommandAudit({
+    command: { type: 'source.stimulus', origin: 'user' },
+    ack: { accepted: true },
+    source: { answered: false },
+    at
+  })
+  assert.equal(row.sourceOutcome, 'unknown')
+})
+
+test('답이 있으면 그대로 적는다 — 거절도 사실이다', () => {
+  const applied = buildCommandAudit({ command: {}, ack: { accepted: true }, source: { answered: true, ok: true }, at })
+  assert.equal(applied.sourceOutcome, 'applied')
+  const refused = buildCommandAudit({
+    command: {},
+    ack: { accepted: true },
+    source: { answered: true, ok: false, code: 'not-declared' },
+    at
+  })
+  assert.equal(refused.sourceOutcome, 'refused')
+  assert.equal(refused.sourceCode, 'not-declared', '원본이 준 사유를 그대로 적는다')
+})
+
+test('사유가 없으면 사유 칸도 없다 — 지어내지 않는다', () => {
+  const row = buildCommandAudit({ command: {}, ack: { accepted: true }, source: { answered: true, ok: true }, at })
+  assert.equal('sourceCode' in row, false)
+})
+
+test('판정 함수가 세 값만 낸다 — ok 가 참/거짓이 아니면 모른다', () => {
+  assert.equal(sourceOutcomeOf({ answered: true, ok: true }), 'applied')
+  assert.equal(sourceOutcomeOf({ answered: true, ok: false }), 'refused')
+  assert.equal(sourceOutcomeOf({ answered: false }), 'unknown')
+  assert.equal(sourceOutcomeOf({ answered: true }), 'unknown', '답했다고 하면서 값이 없으면 모르는 것이다')
+  assert.equal(sourceOutcomeOf({ answered: true, ok: undefined as any }), 'unknown')
+})
+
+test('신원은 여전히 서버만 채운다 — 원본의 답이 그 규율을 흔들지 않는다', () => {
+  const row = buildCommandAudit({
+    command: { type: 'source.pause', origin: 'user', actorId: 'forged', actorEmail: 'forged@x' },
+    ack: { accepted: true },
+    source: { answered: true, ok: true },
+    at,
+    actor: { id: 'u1', email: 'real@x' }
+  })
+  assert.equal(row.actorId, 'u1')
+  assert.equal(row.actorEmail, 'real@x')
+})
+
+/*
+ * ── 구동 문이 실제로 남기는지 (소스로 지킨다) ───────────────────────────────
+ * 순수 함수만 시험하면 「기록을 만들 수 있다」까지만 지킨다. 남기지 않으면 그 함수는 아무 일도 하지 않는다.
+ */
+test('구동 문이 게이트 뒤에서 원본의 답까지 남긴다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/twin-control/twin-control-mutation.ts', import.meta.url)), 'utf-8')
+  const code = src
+    .split('\n')
+    .filter(line => !/^\s*(\*|\/\/|\/\*)/.test(line))
+    .join('\n')
+  /* 게이트는 남는다(결정 C 의 절반). */
+  const gates = code.match(/@privilege\(category: "twin", privilege: "mutation"/g) ?? []
+  assert.ok(gates.length >= 2, `구동 문에도 게이트가 있어야 한다(발견 ${gates.length})`)
+  /* 원본의 답을 같은 행에 닫는다. */
+  assert.match(code, /source: \{ answered: typeof result\?\.ok === 'boolean', ok: result\?\.ok, code: result\?\.code \}/)
+  assert.match(code, /type: `source\.\$\{action\}`/, '커맨드 채널과 같은 어휘로 적는다')
+  /* 기록 실패를 삼키지 않는다. */
+  assert.match(code, /source control audit not recorded/)
+})
+
+test('엔티티가 그 두 칸을 든다 — 비어 있음이 뜻을 갖는다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/twin-audit/twin-audit-event.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /sourceOutcome\?: string/)
+  assert.match(src, /sourceCode\?: string/)
+  assert.match(src, /the source was not asked/, '비어 있음의 뜻을 필드 설명이 말한다')
+})

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

@@ -95,9 +95,9 @@ beforeEach(async () => {
 
 test('같은 구조로 다시 프로비저닝하면 리비전이 늘지 않는다 — 부팅마다 늘면 이력이 잘게 쪼개진다', async () => {
   const model = boardWith(2, 1)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', JSON.parse(JSON.stringify(model)))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', JSON.parse(JSON.stringify(model)), 'reset')
 
   const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   assert.equal(revs.length, 1)
@@ -105,12 +105,12 @@ test('같은 구조로 다시 프로비저닝하면 리비전이 늘지 않는
 })
 
 test('구조가 바뀌면 새 리비전이 생기고 **저널은 살아남는다**', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   assert.ok(first.length > 0, '이벤트가 있어야 "살아남는지" 를 물을 수 있다')
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
 
   const kept = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   assert.equal(kept, first.length, '구조가 바뀌었다고 이력을 지우면 안 된다 — 그것이 이 작업의 전부다')
@@ -121,9 +121,9 @@ test('구조가 바뀌면 새 리비전이 생기고 **저널은 살아남는다
 })
 
 test('이벤트가 자기 구조 번호를 달고 저장된다 — 안 달면 나중에 어느 공장인지 알 길이 없다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(2, 1), 200), 0)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
   const before = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 200), before)
 
@@ -135,11 +135,11 @@ test('이벤트가 자기 구조 번호를 달고 저장된다 — 안 달면
 })
 
 test('★ 재생이 경계를 넘는다 — 앞선 사실은 남고, 새 구조의 설비가 들어온다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
   await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 300), first.length)
 
   const state = await TwinEngine.recover(domainId, INSTANCE)
@@ -153,20 +153,20 @@ test('구조 번호가 없는 옛 행은 **가장 오래된 구조**로 접는
    * 컬럼이 생기기 전에 쓰인 행은 `structureRev` 가 비어 있다. 그것을 현재 보드로 접으면 그때 없던
    * 설비에서 일이 있었던 것처럼 보인다 — 이 규칙이 그 행들을 제자리에 붙인다.
    */
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const legacy = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, legacy, 0)
   /* 컬럼이 없던 시절을 흉내 낸다 — 번호를 지운다. */
   await ds.query(`UPDATE "${ds.getMetadata(TwinEvent).tableName}" SET structure_rev = NULL`)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
   const state = await TwinEngine.recover(domainId, INSTANCE)
   assert.ok(state.items.length > 0, '번호 없는 옛 행도 읽혀야 한다 — 조용히 버리지 않는다')
   assert.equal(state.equipment.length, 3, '마지막 구조가 자원의 진실이다')
 })
 
 test('리비전이 하나뿐이면 예전과 똑같이 접는다 — 구조 전환이 결과를 바꾸지 않는다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(3, 2))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(3, 2), 'reset')
   const events = realEvents(boardWith(3, 2), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, events, 0)
 
@@ -177,7 +177,7 @@ test('리비전이 하나뿐이면 예전과 똑같이 접는다 — 구조 전
 })
 
 test('꺼진 트윈의 이력도 읽을 수 있다 — 저널은 트윈이 꺼져 있을 때 가장 필요하다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   assert.equal(TwinEngine.owns(domainId, INSTANCE), false, '떠 있지 않다')
   assert.equal(await TwinEngine.ownsRegistered(domainId, INSTANCE), true, '그래도 이 테넌트 것이다')
   assert.equal(await TwinEngine.ownsRegistered(domainId, 'someone-elses-twin'), false)
@@ -189,11 +189,11 @@ test('시간여행은 **그때의 공장**을 보여준다 — 과거에 최신
    * 그런데 그 규칙을 과거 조회에도 적용하면, 그 시점에 존재하지도 않던 설비가 화면에 선다 —
    * 이 작업이 막으려던 바로 그 거짓말이다. 규칙이 "지금" 에만 걸리는지 못박는다.
    */
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
 
   const now = await TwinEngine.recover(domainId, INSTANCE)
   assert.equal(now.equipment.length, 3, '"지금" 은 늘린 설비를 보여준다')
@@ -204,10 +204,10 @@ test('시간여행은 **그때의 공장**을 보여준다 — 과거에 최신
 })
 
 test('구조 이력이 **무엇이 달라졌는지** 알린다 — 보드 두 개를 눈으로 비교할 수는 없다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 200)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), '도장 능력 보강')
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset', '도장 능력 보강')
   await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 100), first.length)
 
   const history = await TwinEngine.structureHistory(domainId, INSTANCE)
@@ -232,11 +232,11 @@ test('구조 이력이 **무엇이 달라졌는지** 알린다 — 보드 두
 })
 
 test('번호 없는 옛 행도 가장 오래된 리비전의 몫으로 센다 — 재생과 같은 규칙', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const legacy = realEvents(boardWith(2, 1), 200)
   await TwinEngine.persistBatch(domainId, INSTANCE, legacy, 0)
   await ds.query(`UPDATE "${ds.getMetadata(TwinEvent).tableName}" SET structure_rev = NULL`)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
 
   const history = await TwinEngine.structureHistory(domainId, INSTANCE)
   assert.equal(history[0].events, legacy.length, '재생이 rev 1 로 접는 행들을 세는 쪽만 빠뜨리면 두 화면이 다른 말을 한다')
@@ -250,11 +250,11 @@ test('지문 표기가 낡았을 뿐이면 리비전을 만들지 않는다 —
    * 그런 일이 없다.
    */
   const model = boardWith(2, 1)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
   const table = ds.getMetadata(TwinStructure).tableName
   await ds.query(`UPDATE "${table}" SET signature = 'old-style-signature-from-a-previous-algorithm'`)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
 
   const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   assert.equal(revs.length, 1, '공장은 그대로인데 리비전이 늘면 이력이 거짓으로 부푼다')
@@ -269,11 +269,11 @@ test('지문 표기가 낡았을 뿐이면 리비전을 만들지 않는다 —
  * 행과 겹치는 문제였다. 그 겹침은 오류를 내지 않고 조용히 재생 순서를 뒤섞는다.
  */
 test('sim-world 로 다시 띄워도 저널이 살아남는다 — 선언이 지키는 약속', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
   try {
     const kept = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
     assert.equal(kept, first.length, 'sim-world 는 이어지는 현실이다 — 지우면 선언이 거짓이 된다')
@@ -283,11 +283,11 @@ test('sim-world 로 다시 띄워도 저널이 살아남는다 — 선언이 지
 })
 
 test('★ 재기동 후 새 이벤트는 마지막 번호 뒤에 온다 — 겹치면 재생 순서가 뒤섞인다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
   try {
     const kernel: any = rt.kernel
     assert.ok(kernel, '커널이 떠야 이어 세기를 물을 수 있다')
@@ -301,8 +301,8 @@ test('★ 재기동 후 새 이벤트는 마지막 번호 뒤에 온다 — 겹
 })
 
 test('저널이 비어 있으면 이어 셀 것이 없다 — 새로 시작하는 트윈에 영향 없음', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
   try {
     assert.equal((rt.kernel as any).getSnapshot().revision, 0)
   } finally {

package/test/tenant-registry-db.test.ts

@@ -61,8 +61,8 @@ before(async () => {
   beta = b.id
 
   /* 두 테넌트가 **같은 id** 로 각자 프로비저닝한다 — DB 유일성이 `[domain, instanceId]` 라 허용된다. */
-  await TwinEngine.provision(alpha, SHARED_ID, 'wms', model())
-  await TwinEngine.provision(beta, SHARED_ID, 'wms', model())
+  await TwinEngine.provision(alpha, SHARED_ID, 'wms', model(), 'reset')
+  await TwinEngine.provision(beta, SHARED_ID, 'wms', model(), 'reset')
 })
 
 /**

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

@@ -85,7 +85,7 @@ before(async () => {
   q = new TwinModelItemQuery()
   ctx = { state: { domain: { id: domainId } } }
 
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 after(async () => {
@@ -213,7 +213,7 @@ test('지도의 선이 진단이 된다 — 이어진 것뿐 아니라 **끊긴
   const bad = master()
   bad.equipment.push({ id: 'ghost-1', kind: 'welder', homeLocationId: 'no-such-station' }) // 끊어진 참조
   bad.equipment.push({ id: 'floater-1', kind: 'welder' })                                   // 기준 자리 없음
-  await TwinEngine.ingestMaster(domainId, bad)
+  await TwinEngine.ingestMaster(domainId, bad, 'reset')
 
   const sum = await new TwinModelQuery().twinModelSummary(INSTANCE, ctx)
   const home = sum.edges.find((e: any) => e.from === 'equipment' && e.to === 'locations' && e.via === 'twin.rel.home')
@@ -263,7 +263,7 @@ test('멈춘 트윈도 저널을 접어 답하고, 그 답은 다시 계산한
   for (let i = 0; i < 200; i++) k.tick(1000)
 
   const INST = 'journal-probe'
-  await TwinEngine.provision(domainId, INST, 'wms', model)
+  await TwinEngine.provision(domainId, INST, 'wms', model, 'reset')
   await TwinEngine.persistBatch(domainId, INST, journal.all(), 0)
   await TwinEngine.stop(domainId, INST).catch(() => {})
   delete (TwinEngine as any).recovered[`${domainId}:${INST}`]