@things-factory/headless-twin 10.0.10 → 10.0.12

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}`]

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

@@ -76,7 +76,7 @@ before(async () => {
   domainId = d.id
   q = new TwinModelTreeQuery()
   ctx = { state: { domain: { id: domainId } } }
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 after(async () => {
@@ -108,13 +108,13 @@ test('수량을 곱해 내려간다 — 그리고 모르면 곱하지 않는다'
       { key: 'frame-line', label: 'f', inputs: [{ material: 'steel', qty: 4 }], outputs: [{ material: 'frame', qty: 1 }] }
     ]
   })
-  await TwinEngine.ingestMaster(domainId, noQty)
+  await TwinEngine.ingestMaster(domainId, noQty, 'reset')
   const t2 = await explode('trailer')
   assert.equal(t2.items.find((n: any) => n.id === 'frame').qty, null, '모르는 수량을 1 로 메우지 않는다')
   assert.equal(t2.items.find((n: any) => n.id === 'steel').qty, null, '모르는 값 아래는 전부 모르는 값이다')
   assert.equal(t2.qtyIncomplete, true, '합계가 성립하지 않는다는 사실을 낸다')
 
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 test('역전개도 같은 선언으로 — 방향만 뒤집는다', async () => {
@@ -146,11 +146,11 @@ test('사이클은 다시 탐색하지 않고 알린다', async () => {
       { key: 'frame-line', label: 'f', inputs: [{ material: 'trailer', qty: 1 }], outputs: [{ material: 'frame', qty: 1 }] }
     ]
   })
-  await TwinEngine.ingestMaster(domainId, loop)
+  await TwinEngine.ingestMaster(domainId, loop, 'reset')
   const t = await explode('trailer')
   assert.ok(t.items.length < 10, '무한히 자라지 않는다')
   assert.ok(t.cycles.length > 0, '사이클을 만났다는 사실을 말한다')
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 test('상한에서 끊기면 끊겼다고 알린다 — 조용히 자르지 않는다', async () => {
@@ -167,10 +167,10 @@ test('선언에 없는 자재를 참조하면 그 사실이 드러난다', async
       { key: 'trailer-line', label: 't', inputs: [{ material: 'no-such-part', qty: 1 }], outputs: [{ material: 'trailer', qty: 1 }] }
     ]
   })
-  await TwinEngine.ingestMaster(domainId, ghost)
+  await TwinEngine.ingestMaster(domainId, ghost, 'reset')
   const t = await explode('trailer')
   const child = t.items.find((n: any) => n.id === 'no-such-part')
   assert.ok(child, '가리켜진 것은 그리되')
   assert.equal(child.known, false, '선언에 없다는 사실을 함께 낸다(있는 척하지 않는다)')
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })

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

@@ -68,7 +68,7 @@ after(async () => {
 })
 
 test('인제스트가 원천을 각인한다 — 원천이 무엇이든 한 자리에', async () => {
-  await TwinEngine.ingestMaster(domainId, master(BORN, 3, { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } }))
+  await TwinEngine.ingestMaster(domainId, master(BORN, 3, { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } }), 'reset')
   assert.deepEqual(await originOf(BORN), { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } })
 })
 
@@ -78,7 +78,7 @@ test('원천을 모르는 재프로비전이 이미 아는 것을 지우지 않
    * 인제스트한다. 그때 `origin` 을 덮어 비우면 그 트윈은 **조용히 다시 읽을 수 없게 된다.**
    * 그런 종류의 손상은 다음번에 다시 읽으려 할 때까지 아무도 모른다.
    */
-  await TwinEngine.ingestMaster(domainId, master(BORN, 5))
+  await TwinEngine.ingestMaster(domainId, master(BORN, 5), 'reset')
   assert.deepEqual(
     await originOf(BORN),
     { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } },
@@ -90,12 +90,12 @@ test('원천을 모르는 재프로비전이 이미 아는 것을 지우지 않
 })
 
 test('새 원천을 말하면 갱신된다 — 보존은 침묵에만 적용된다', async () => {
-  await TwinEngine.ingestMaster(domainId, master(BORN, 5, { kind: 'reference', source: 'oracle-wms' }))
+  await TwinEngine.ingestMaster(domainId, master(BORN, 5, { kind: 'reference', source: 'oracle-wms' }), 'reset')
   assert.deepEqual(await originOf(BORN), { kind: 'reference', source: 'oracle-wms' })
 })
 
 test('원천 없이 태어난 트윈은 원천이 없다 — 짐작해 채우지 않는다', async () => {
-  await TwinEngine.ingestMaster(domainId, master(ORPHAN, 2))
+  await TwinEngine.ingestMaster(domainId, master(ORPHAN, 2), 'reset')
   assert.equal(await originOf(ORPHAN), null, '모르는 것을 아는 척하면 엉뚱한 원본으로 현장을 덮는다')
 })
 

package/test/yield-loop.test.ts

@@ -0,0 +1,144 @@
+/*
+ * **한 바퀴** — 커널이 라인을 돌리고, 그 이벤트를 접어, 배운 수율이 다시 커널로 들어간다.
+ *
+ * ── 왜 이 시험이 필요했나 (2026-08-19) ─────────────────────────────────────
+ * 층마다 시험이 있었다(커널 7 · 호스트 9). 그런데 **사슬이 이어졌는지**는 층 시험으로 알 수 없다 —
+ * 이벤트 모양이 한 칸만 어긋나도 각 층은 통과하면서 전체는 조용히 상수로 돈다.
+ *
+ * 실 앱에서 보려고 데모 MES 트윈으로 한 바퀴를 돌리려 했는데 두 번 막혔다: ① 데모의 자극(시나리오)은
+ * **시드 때만 실려서** 트윈을 재기동하면 사라진다 ② 모델에서 읽은 값으로 자극을 재구성했지만 부품 도착이
+ * 레시피 입력과 맞물리지 않아 라인이 돌지 않았다. 그 두 개는 **데모 데이터의 문제**이고, 우리가 증명해야
+ * 하는 것(사슬)과는 다른 문제다.
+ *
+ * 그래서 여기서 **DB·서버 없이** 진짜 사슬을 돌린다: 커널(MES) → `task.status` 이벤트 → 호스트의 실제
+ * 폴드(`foldKpi`) → 실제 추정기(`buildYieldEstimator`) → 커널 시임. 가짜 이벤트를 손으로 만들지 않는다 —
+ * 커널이 낸 것을 그대로 접는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+
+import { foldKpi } from '../server/engine/kpi-fold.ts'
+import { buildYieldEstimator } from '../server/engine/measured-yield.ts'
+
+/* 커널은 한 벌로 묶인 산출물로 들어온다(서브패스는 exports 로 막혀 있다 — property-effects 시험과 같은 이유). */
+const require = createRequire(import.meta.url)
+const { MesKernel, MES_PART_GTINS } = require('@operato/twin-kernel')
+
+/** 보드·자극은 커널 시험(`mes.test.ts`)의 것과 같은 모양 — 여기서 공장을 지어내지 않는다. */
+function board() {
+  return {
+    locations: [
+      { id: 'raw-store', type: 'raw-store', capacity: 500 },
+      { id: 'cut-station', type: 'cut-station', capacity: 20 },
+      { id: 'weld-station', type: 'weld-station', capacity: 20 },
+      { id: 'paint-booth', type: 'paint-booth', capacity: 20 },
+      { id: 'assembly-line', type: 'assembly-line', capacity: 20 },
+      { id: 'fg-store', type: 'fg-store', capacity: 200 }
+    ],
+    equipment: [
+      { id: 'cutter-1', kind: 'cutter', homeLocation: 'cut-station' },
+      { id: 'welder-1', kind: 'welder', homeLocation: 'weld-station' },
+      { id: 'painter-1', kind: 'painter', homeLocation: 'paint-booth' },
+      { id: 'assembler-1', kind: 'assembler', homeLocation: 'assembly-line' }
+    ]
+  }
+}
+
+const partsInbound = {
+  seed: 3,
+  generators: [
+    {
+      kind: 'inbound-arrival',
+      rate: { distribution: 'constant', meanPerHour: 720 },
+      content: { skuMix: [{ gtin: MES_PART_GTINS.partA, weight: 1 }, { gtin: MES_PART_GTINS.partB, weight: 1 }], qtyPerLine: { min: 1, max: 1 } }
+    }
+  ]
+}
+const workOrders = {
+  seed: 7,
+  generators: [
+    {
+      kind: 'outbound-order',
+      rate: { distribution: 'constant', meanPerHour: 360 },
+      content: { skuMix: [{ gtin: MES_PART_GTINS.partA, weight: 1 }], qtyPerLine: { min: 1, max: 1 } }
+    }
+  ]
+}
+
+/** 라인을 한 바퀴 돌린다 — 부품을 채우고 작업지시를 흘리고 배수한다. */
+function runLine(declaredYieldPct?: number): { events: any[]; kernel: any } {
+  const k: any = new MesKernel('plantA')
+  const events: any[] = []
+  k.onEvent((e: any) => events.push(e))
+  k.loadTwinModel(board())
+  /* 선언값을 넣어 두면 「실측이 선언을 이긴다」를 같은 라인에서 확인할 수 있다. */
+  if (declaredYieldPct !== undefined) k.declareParameters({ assembly: { yield: String(declaredYieldPct / 100) } })
+  k.scenario.load(partsInbound)
+  k.scenario.start()
+  for (let i = 0; i < 400; i++) k.tick(1000)
+  k.scenario.pause()
+  for (let i = 0; i < 30; i++) k.tick(1000)
+  k.scenario.load(workOrders)
+  k.scenario.start()
+  for (let i = 0; i < 300; i++) k.tick(1000)
+  k.scenario.pause()
+  for (let i = 0; i < 4000; i++) k.tick(1000)
+  return { events, kernel: k }
+}
+
+/** 커널 이벤트를 저널 줄 모양으로 — 호스트가 DB 에서 읽는 것과 같은 모양(payload 안에 data). */
+const asJournal = (events: any[]) =>
+  events.filter(e => e.eventType === 'task.status').map(e => ({ eventType: 'task.status', eventTime: e.eventTime, payload: { data: e.data } }))
+
+const window = (rows: { eventTime: string }[]) => {
+  const times = rows.map(r => Date.parse(r.eventTime)).filter(n => Number.isFinite(n))
+  return { fromMs: Math.min(...times) - 1000, toMs: Math.max(...times) + 1000 }
+}
+
+test('한 바퀴: 커널이 판정을 내고 → 폴드가 종류별로 세고 → 추정기가 비율을 배운다', () => {
+  const { events } = runLine()
+  const rows = asJournal(events)
+  assert.ok(rows.length > 50, `작업 전이가 충분히 나야 한다(관측 ${rows.length})`)
+
+  /* 호스트의 **실제** 폴드로 접는다 — 시험용 계산을 따로 만들지 않는다. */
+  const kpi = foldKpi(rows as any, window(rows as any), { groupBy: 'taskKind' })
+  const judged = (kpi.groups?.items ?? []).filter(g => g.quality)
+  assert.ok(judged.length > 0, '품질이 세어진 종류가 있어야 한다')
+  for (const g of judged) {
+    assert.ok(g.quality!.good + g.quality!.scrap > 0)
+    assert.ok(g.quality!.good + g.quality!.scrap <= g.tasks, '판정 수는 완료 수를 넘지 못한다')
+  }
+  /* 판정이 없는 종류도 있어야 한다 — 중간 스테이션은 품질을 가리지 않는다(분모에 섞이면 안 된다). */
+  assert.ok((kpi.groups?.items ?? []).some(g => !g.quality), '판정하지 않는 공정이 있다')
+
+  const learned = buildYieldEstimator(kpi.groups?.items, { minSamples: 5 })
+  assert.ok(Object.keys(learned.learned).length > 0, '수율을 배워야 한다')
+  for (const [kind, ratio] of Object.entries(learned.learned)) {
+    assert.ok(ratio >= 0 && ratio <= 1, `${kind} 의 비율이 0..1 이어야 한다(관측 ${ratio})`)
+    const s = learned.samples[kind]
+    assert.equal(learned.learned[kind], s.good / (s.good + s.scrap), '비율은 판정 수에서 곧바로 나온다')
+  }
+})
+
+test('배운 값이 커널로 되돌아가 선언값을 이긴다 — 사슬의 마지막 칸', () => {
+  /* 선언 60% 로 라인을 돌린다(그 현장의 이력이 그렇게 남는다). */
+  const { events } = runLine(60)
+  const rows = asJournal(events)
+  const kpi = foldKpi(rows as any, window(rows as any), { groupBy: 'taskKind' })
+  const learned = buildYieldEstimator(kpi.groups?.items, { minSamples: 5 })
+  const kinds = Object.keys(learned.learned)
+  assert.ok(kinds.length > 0, '이력에서 배운 종류가 있어야 한다')
+
+  /* 새 커널에 그 이력을 실으면 — 선언값(90%)이 아니라 이력값으로 답한다. */
+  const k2: any = new MesKernel('plantA')
+  k2.declareParameters(Object.fromEntries(kinds.map(kind => [kind, { yield: '0.9' }])))
+  k2.yieldEstimator = learned.estimator
+  for (const kind of kinds) {
+    assert.equal(k2.yieldOf(kind), learned.learned[kind], `${kind}: 이력값이 이긴다`)
+    assert.deepEqual(k2.specCoverage().operations.find((o: any) => o.kind === kind)?.parameterBasis, { yield: 'measured' })
+  }
+  /* 이력이 없는 종류는 그대로 선언값이다 — 배운 것만 이긴다(전부 덮지 않는다). */
+  k2.declareParameters({ 'never-run': { yield: '0.5' } })
+  assert.equal(k2.yieldOf('never-run'), 0.5)
+})