@things-factory/headless-twin 10.0.18 → 10.1.0

package/test/hook-sequence.test.ts

@@ -0,0 +1,333 @@
+/*
+ * **밀어 받는 길의 번호** — 빠진 것을 알아채고, 재기동을 넘어 이어받는다.
+ *
+ * ── 왜 이 시험이 있나 (2026-08-31) ────────────────────────────────────────
+ * 훅이 놓치는 것은 예외가 아니라 정상이다. 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가
+ * 끊겼을 때. 그 대비가 드문 폴링 하나뿐이었다 — 폴링은 「놓친 것이 있나」를 값으로 알아내는 것이고,
+ * 번호는 빠진 것을 곧바로 안다.
+ *
+ * ── 왜 순수 함수 시험만으로 부족한가 ─────────────────────────────────────
+ * 번호 판정 자체는 계약 쪽에서 확인한다(`ops-contract/test/webhook-contract.test.ts`). 여기서 보는
+ * 것은 **배선**이다 — 판정이 응답이 되는가, 커서에 적히는가, 다시 세운 뒤에 읽히는가.
+ *
+ * 이 저장소에서 가장 자주 나는 결함이 「자리는 있고 길이 없다」이고, 커서가 정확히 그 모양이었다.
+ * `TwinReference.liveCursor` 는 재기동을 넘어 사는 자리인데 **훅 경로가 그것을 읽지도 쓰지도 않았다.**
+ * 쓰는 곳은 폴링 하나뿐이었다.
+ *
+ * 그래서 마지막 시험이 저장본을 그대로 두고 **핸들러를 새로 부른다.** 한 프로세스 안에서만 확인하면
+ * 「적히나」는 보이지만 「다시 세우면 읽히나」는 보이지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { WEBHOOK_STATUS, webhookSenderAction } from '@operato/ops-contract'
+
+import { handleHook, type HookStore } from '../server/service/reference/reference-hook.js'
+import { registerAdapterType, getAdapter } from '../server/service/reference/reference-adapter.js'
+
+const DOMAIN = 'd-1'
+const SOURCE = 'operato-plant'
+const TWIN = 'twin-a'
+const SECRET = 'shared-secret'
+const SCOPE = 'EVENTS'
+/** 커서 열쇠에는 트윈이 함께 들어간다 — 연결 하나가 트윈 여럿을 만든다. */
+const KEY = `${TWIN}::${SCOPE}`
+
+/** 보낸 봉투를 그대로 레코드로 내는 커넥터 — 옮길 것이 없으므로 번호만 꺼낸다. */
+const ADAPTER_TYPE = 'test-numbered-push'
+if (!getAdapter(ADAPTER_TYPE)) {
+  registerAdapterType({
+    type: ADAPTER_TYPE,
+    label: 'numbered push (test)',
+    handleInbound: (_cfg: any, _site: any, body: any) => ({
+      items: body?.items ?? [{ record: { moverId: 'eq-1', kind: 'press', status: 'idle' }, seq: body?.seq }],
+      scope: body?.scope
+    })
+  } as any)
+}
+
+/** 저장본 하나 — 프로세스가 아니라 여기에 산다. 그래서 핸들러를 새로 불러도 남는다. */
+function makeStore(initial?: unknown): HookStore & { row: any } {
+  const row = {
+    id: 'ref-1',
+    source: SOURCE,
+    adapterType: ADAPTER_TYPE,
+    connectionConfig: { hookSecret: SECRET },
+    scopeSpec: { produced: [{ siteId: 'site-a', instanceId: TWIN }] },
+    liveCursor: initial
+  }
+  return {
+    row,
+    load: async (domainId: string, source: string) => (domainId === DOMAIN && source === SOURCE ? row : null),
+    saveCursor: async (refId: string, cursor: unknown) => {
+      assert.equal(refId, row.id)
+      /* 저장소를 흉내 내는 것이라 참조를 그대로 두지 않고 복사해 넣는다 — 같은 객체면 안 적혀도 통과한다. */
+      row.liveCursor = JSON.parse(JSON.stringify(cursor))
+    }
+  }
+}
+
+const applied = (_id: string, records: unknown[]) => ({ applied: records.length, duplicates: 0, rejected: [] })
+
+function push(store: HookStore, seq: number | undefined, opts: { scope?: string; ingest?: any } = {}) {
+  return handleHook({
+    domainId: DOMAIN,
+    source: SOURCE,
+    instanceId: TWIN,
+    headers: { 'x-twin-hook-secret': SECRET },
+    body: { seq, scope: 'scope' in opts ? opts.scope : SCOPE },
+    nowMs: Date.parse('2026-08-31T02:00:00.000Z'),
+    ingest: opts.ingest ?? applied,
+    store
+  })
+}
+
+test('★ 첫 봉투를 받고 그 번호를 커서에 적는다', async () => {
+  const store = makeStore()
+  const out = await push(store, 918342)
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.sequenceChecked, true)
+  assert.equal(out.body.lastSeq, 918342)
+  assert.equal(store.row.liveCursor?.streams?.[KEY]?.seq, 918342, '커서에 적히지 않았다')
+})
+
+test('★ 건너뛴 번호는 409 로 답하고 그 앞부터 달라고 한다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await push(store, 7)
+
+  assert.equal(out.status, WEBHOOK_STATUS.sequenceGap)
+  assert.equal(out.body.expectedSeq, 5)
+  assert.equal(out.body.lastSeq, 4)
+  assert.equal(out.body.scope, SCOPE, '어느 줄의 번호인지 함께 말한다')
+})
+
+test('★ 구멍이 났을 때 커서를 올리지 않는다 — 올리면 그 구간이 영영 안 온다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  await push(store, 7)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 4)
+})
+
+test('★ 이미 본 번호는 받아들이되 커서를 뒤로 끌지 않는다 — 재전송이 정상 동작이다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 9 } } })
+  const out = await push(store, 9)
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 9)
+})
+
+test('★ 반영되지 않았으면 커서를 올리지 않는다 — 트윈이 안 도는 사이의 번호를 지나치면 그 구간이 빈다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await push(store, 5, { ingest: () => ({ applied: 0, duplicates: 0, rejected: [] }) })
+
+  assert.equal(out.status, WEBHOOK_STATUS.notLive)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 4, '한 건도 안 들어갔는데 번호가 올라갔다')
+})
+
+test('★ 번호를 매기지 않는 원본은 확인하지 않고, 확인하지 않았다고 말한다', async () => {
+  /* chef · ppms 가 그렇다. 「확인했고 이상 없다」와 같아 보이면 어느 연결이 지켜지는지 알 수 없다. */
+  const store = makeStore()
+  const out = await push(store, undefined, { scope: undefined })
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.sequenceChecked, false)
+  assert.equal(store.row.liveCursor, undefined, '번호가 없으면 커서를 만들지 않는다')
+})
+
+test('★ 번호만 있고 어느 줄인지 없으면 확인하지 않는다 — 짐작한 열쇠는 줄이 늘면 어긋난다', async () => {
+  const store = makeStore()
+  const out = await push(store, 918342, { scope: undefined })
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.sequenceChecked, false)
+})
+
+test('★ 줄마다 번호가 따로 간다 — 두 줄이 한 커서에 섞이면 끊임없이 「빠졌다」가 된다', async () => {
+  const store = makeStore()
+  await push(store, 5, { scope: 'EVENTS' })
+  await push(store, 1, { scope: 'MASTER' })
+
+  assert.equal(store.row.liveCursor.streams[`${TWIN}::EVENTS`].seq, 5)
+  assert.equal(store.row.liveCursor.streams[`${TWIN}::MASTER`].seq, 1)
+
+  /* MASTER 의 1 이 EVENTS 의 5 를 되돌리지 않았으므로 EVENTS 6 이 그대로 이어진다. */
+  assert.equal((await push(store, 6, { scope: 'EVENTS' })).status, WEBHOOK_STATUS.ok)
+})
+
+test('★ 재기동을 넘어 이어받는다 — 저장본만 남기고 핸들러를 새로 부른다', async () => {
+  const first = makeStore()
+  await push(first, 5)
+  const saved = JSON.parse(JSON.stringify(first.row.liveCursor))
+
+  /* 프로세스가 새로 선 것으로 본다 — 앞의 저장소 객체는 버리고 저장본만 물려준다. */
+  const second = makeStore(saved)
+
+  assert.equal((await push(second, 7)).status, WEBHOOK_STATUS.sequenceGap, '이어받지 못하면 7 이 그냥 통과한다')
+  assert.equal((await push(second, 6)).status, WEBHOOK_STATUS.ok)
+  assert.equal(second.row.liveCursor.streams[KEY].seq, 6)
+})
+
+test('★ 커서를 적지 못해도 이미 들어간 사실을 무르지 않는다 — 다음 번호에서 구멍으로 드러난다', async () => {
+  const store = makeStore()
+  const broken: HookStore = { load: store.load, saveCursor: async () => { throw new Error('disk full') } }
+
+  const out = await push(broken, 5)
+  assert.equal(out.status, WEBHOOK_STATUS.ok, '유입은 이미 끝났다 — 커서를 못 적은 것이 그것을 무를 이유가 아니다')
+})
+
+/* ── 한 요청에 봉투 여럿 ──────────────────────────────────────────────────── */
+
+/** 번호가 붙은 봉투 여럿을 한 요청으로 보낸다 — 밀어 주는 쪽은 한 건씩 보내지 않는다. */
+function pushBatch(store: HookStore, seqs: number[], opts: { scope?: string; ingest?: any } = {}) {
+  return handleHook({
+    domainId: DOMAIN,
+    source: SOURCE,
+    instanceId: TWIN,
+    headers: { 'x-twin-hook-secret': SECRET },
+    body: {
+      scope: 'scope' in opts ? opts.scope : SCOPE,
+      items: seqs.map(seq => ({ seq, record: { moverId: `eq-${seq}`, kind: 'press', status: 'idle' } }))
+    },
+    nowMs: Date.parse('2026-08-31T02:00:00.000Z'),
+    ingest: opts.ingest ?? applied,
+    store
+  })
+}
+
+test('★ 배치 가운데가 빠지면 그 앞까지만 받는다 — 구멍 뒤를 받으면 그 구멍이 영영 안 메워진다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const taken: unknown[][] = []
+  const out = await pushBatch(store, [5, 6, 9, 10], {
+    ingest: (_id: string, records: unknown[]) => {
+      taken.push(records)
+      return { applied: records.length, duplicates: 0, rejected: [] }
+    }
+  })
+
+  assert.equal(taken[0].length, 2, '5·6 만 넣어야 한다')
+  assert.equal(out.status, WEBHOOK_STATUS.sequenceGap)
+  assert.equal(out.body.expectedSeq, 7)
+  assert.equal(out.body.lastSeq, 6, '앞의 것은 받았다는 것을 함께 말한다 — 안 그러면 5·6 을 또 보낸다')
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 6)
+})
+
+test('★ 배치 전체가 이어지면 끝 번호가 커서가 된다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await pushBatch(store, [5, 6, 7])
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.lastSeq, 7)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 7)
+})
+
+test('★ 첫 봉투부터 구멍이면 아무것도 넣지 않고 커서도 그대로다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  let called = false
+  const out = await pushBatch(store, [9, 10], {
+    ingest: () => {
+      called = true
+      return { applied: 2, duplicates: 0, rejected: [] }
+    }
+  })
+
+  assert.equal(called, false, '받을 것이 없는데 유입을 불렀다')
+  assert.equal(out.status, WEBHOOK_STATUS.sequenceGap)
+  assert.equal(out.body.expectedSeq, 5)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 4)
+})
+
+test('★ 번호가 있는 봉투와 없는 봉투를 섞으면 받지 않는다 — 반쯤 확인한 것을 확인했다고 말하지 않는다', async () => {
+  const store = makeStore()
+  const out = await handleHook({
+    domainId: DOMAIN,
+    source: SOURCE,
+    instanceId: TWIN,
+    headers: { 'x-twin-hook-secret': SECRET },
+    body: { scope: SCOPE, items: [{ seq: 1, record: {} }, { record: {} }] },
+    nowMs: Date.parse('2026-08-31T02:00:00.000Z'),
+    ingest: applied,
+    store
+  })
+
+  assert.equal(out.status, WEBHOOK_STATUS.badPayload)
+  assert.match(String(out.body.error), /mixed batch/)
+})
+
+/* ── 일부만 떨어졌을 때 ───────────────────────────────────────────────────── */
+
+const REJECT_ONE = (_id: string, records: unknown[]) => ({
+  applied: records.length - 1,
+  duplicates: 0,
+  rejected: [{ record: records[records.length - 1], errors: ['equipment: 계약에 없는 필드 — foo'] }]
+})
+
+test('★ 일부가 떨어지면 422 로 답하고 무엇이 떨어졌는지 함께 준다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await pushBatch(store, [5, 6], { ingest: REJECT_ONE })
+
+  assert.equal(out.status, WEBHOOK_STATUS.partial)
+  assert.equal((out.body.rejected as any[]).length, 1)
+  assert.match(String((out.body.rejected as any[])[0].errors[0]), /계약에 없는 필드/)
+})
+
+test('★ 떨어진 것이 있어도 다시 보내라고 하지 않는다 — 나머지는 이미 들어갔다', async () => {
+  assert.equal(webhookSenderAction(WEBHOOK_STATUS.partial), 'partial')
+  assert.notEqual(webhookSenderAction(WEBHOOK_STATUS.partial), 'resend-from')
+})
+
+test('★ 일부가 떨어져도 받은 데까지 커서가 간다 — 안 그러면 그 구간이 매번 다시 온다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await pushBatch(store, [5, 6], { ingest: REJECT_ONE })
+
+  assert.equal(out.body.lastSeq, 6)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 6)
+})
+
+test('★ 구멍과 떨어진 것이 함께 나면 한 응답에 둘 다 싣는다', async () => {
+  /* 두 소식이 갈라져 오면 보내는 쪽은 둘 중 하나만 한다. */
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await pushBatch(store, [5, 6, 9], { ingest: REJECT_ONE })
+
+  assert.equal(out.status, WEBHOOK_STATUS.sequenceGap, '연속성이 먼저다 — 그것이 다음에 무엇을 보낼지 정한다')
+  assert.equal(out.body.expectedSeq, 7)
+  assert.equal(out.body.lastSeq, 6)
+  assert.equal((out.body.rejected as any[]).length, 1, '떨어진 것도 함께 알린다')
+})
+
+test('전부 통과하면 떨어진 목록이 빈다 — 없는 것과 안 본 것이 같아 보이지 않게', async () => {
+  const store = makeStore()
+  const out = await pushBatch(store, [1, 2])
+  assert.deepEqual(out.body.rejected, [])
+})
+
+test('★ 한 연결이 만든 두 트윈이 계수기를 함께 쓰지 않는다', async () => {
+  /*
+   * 커서는 연결마다 한 행에 산다(`TwinReference.liveCursor`). 그런데 연결 하나가 트윈 여럿을 만든다.
+   * 보내는 쪽의 단위 이름만으로 열쇠를 잡으면 두 공장이 한 계수기를 쓰고, B 의 1 이 A 의 5 뒤에서
+   * 「이미 본 번호」로 버려진다.
+   */
+  const store = makeStore()
+  const other = 'twin-b'
+  store.row.scopeSpec.produced.push({ siteId: 'site-b', instanceId: other })
+
+  const send = (instanceId: string, seq: number) =>
+    handleHook({
+      domainId: DOMAIN,
+      source: SOURCE,
+      instanceId,
+      headers: { 'x-twin-hook-secret': SECRET },
+      body: { scope: SCOPE, items: [{ seq, record: { moverId: 'eq-1', kind: 'press', status: 'idle' } }] },
+      nowMs: Date.parse('2026-08-31T02:00:00.000Z'),
+      ingest: applied,
+      store
+    })
+
+  await send(TWIN, 5)
+  const first = await send(other, 1)
+  assert.equal(first.status, WEBHOOK_STATUS.ok, 'B 공장의 첫 봉투가 A 공장의 번호에 걸려 버려졌다')
+
+  assert.equal(store.row.liveCursor.streams[`${TWIN}::${SCOPE}`].seq, 5)
+  assert.equal(store.row.liveCursor.streams[`${other}::${SCOPE}`].seq, 1)
+
+  assert.equal((await send(TWIN, 6)).status, WEBHOOK_STATUS.ok, 'A 공장이 B 의 번호에 끌려갔다')
+})

package/test/ingest-dedupe.test.ts

@@ -0,0 +1,56 @@
+/*
+ * 같은 사실을 두 번 받았을 때 한 번으로 세는 근거 — **정체**.
+ *
+ * 정체를 못 만들면 그 사실은 dedupe 밖이고, 다시 받을 때마다 저널에 새로 앉는다. backfill 이 그것을
+ * 드러냈다(2026-09-06).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { factIdentity, takeUnidentified } from '../server/engine/ingest-dedupe.js'
+
+/* ── 주체가 subjectId 인 사실 ───────────────────────────────────────────────── */
+
+test('★ 처분과 시험은 subjectId 가 주체다 — 그 이름이 없으면 정체가 안 만들어진다', () => {
+  /*
+   * [측정함 2026-09-06] `fillTwinScope` 를 돌릴 때마다 처분 4건 · 시험 3건이 다시 앉았다. 나머지
+   * 34건은 걸러지는데 이 둘만 계속 늘었다.
+   *
+   * 원인은 `discriminatorsOf` 에 `subjectId` 가 없어서 `parts` 가 비고, `factIdentity` 가
+   * `undefined` 를 낸 것이다. 정체가 없으면 dedupe 밖이다.
+   */
+  const disposition = {
+    eventType: 'nonconformance.disposition',
+    eventTime: '2026-09-01T02:50:51.832Z',
+    data: { subjectId: 'LOT-A', decision: 'scrap', quantity: 50 }
+  }
+  const id = factIdentity(disposition)
+  assert.ok(id, '정체를 못 만들면 다시 받을 때마다 새로 앉는다')
+  assert.ok(id!.includes('subject=LOT-A'), `주체가 정체에 안 들어갔다: ${id}`)
+})
+
+test('★ 다른 로트의 같은 처분은 다른 사실이다', () => {
+  const at = '2026-09-01T02:50:51.832Z'
+  const a = factIdentity({ eventType: 'nonconformance.disposition', eventTime: at, data: { subjectId: 'LOT-A', decision: 'scrap' } })
+  const b = factIdentity({ eventType: 'nonconformance.disposition', eventTime: at, data: { subjectId: 'LOT-F', decision: 'scrap' } })
+  assert.notEqual(a, b, '두 로트의 처분이 한 사실로 뭉쳤다')
+})
+
+test('★ 같은 사실을 다시 받으면 같은 정체다 — backfill 이 저널을 안 부풀린다', () => {
+  const rec = { eventType: 'nonconformance.disposition', eventTime: '2026-09-01T02:50:51.832Z', data: { subjectId: 'LOT-A', decision: 'scrap', quantity: 50 } }
+  assert.equal(factIdentity(rec), factIdentity({ ...rec, data: { ...rec.data } }))
+})
+
+test('★ 시험 결과는 명세도 가른다 — 같은 대상에 시험이 여럿이다', () => {
+  const at = '2026-09-01T00:00:00.000Z'
+  const a = factIdentity({ eventType: 'test.result', eventTime: at, data: { subjectId: 'EQ-1', specId: 'CP-PBA-INCOMING' } })
+  const b = factIdentity({ eventType: 'test.result', eventTime: at, data: { subjectId: 'EQ-1', specId: 'CP-PBA-TEST' } })
+  assert.notEqual(a, b, '같은 대상의 두 시험이 한 사실로 뭉쳤다')
+})
+
+test('★ 정체를 못 만든 것을 센다 — 조용히 dedupe 밖으로 나가지 않는다', () => {
+  takeUnidentified()
+  assert.equal(factIdentity({ eventType: 'made.up.kind', eventTime: '2026-09-01T00:00:00.000Z', data: {} }), undefined)
+  assert.deepEqual(takeUnidentified(), { 'made.up.kind': 1 })
+  assert.deepEqual(takeUnidentified(), {}, '읽고 비운다')
+})

package/test/ingest-expected-quiet.test.ts

@@ -0,0 +1,111 @@
+/*
+ * ★ **지금은 조용한 것이 정상이다** — 밤마다 나던 거짓 빨강.
+ *
+ * ── 무엇이 틀렸나 (2026-09-04) ──────────────────────────────────────────────
+ * 유입 건강이 **한 자로 전부를 쟀다.** 10분 안에 아무것도 오지 않으면 「유입 없음」이다. 그런데
+ * 태양광은 밤에 발전하지 않고, 업무시간만 도는 원천은 저녁에 아무것도 내지 않는다. 정상인데
+ * **매일 밤 절반이 빨갛게 났다.**
+ *
+ * 거짓 빨강이 쌓이면 진짜 빨강도 같이 안 읽힌다. 오늘 UX 레인이 「늘 참인 경고는 벽지가 된다」고
+ * 한 것과 같은 부류다 — 사흘이면 그 자리에 무엇이 적혀도 안 읽는다.
+ *
+ * 그리고 15분마다 긷는 원천은 긷는 사이마다 빨갛다. 이 파일이 고치는 코드가 그 한계를 **스스로
+ * 주석에 적어 두고 있었다**: 「주기를 알게 되면 그 값으로 견주는 것이 맞다」.
+ *
+ * ── 초록도 빨강도 아닌 셋째 값 ──────────────────────────────────────────────
+ * 조용한 시간을 초록으로 칠하면 **밤에 정말 끊긴 원천**을 아침까지 아무도 모른다. 그래서 답은
+ * 「지금은 안 오는 것이 맞다」이고, 그것은 다른 값이어야 한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { syncVerdictOf, STALE_AFTER_MS } from '../server/engine/ingest-health.js'
+
+const NOW = 1_800_000_000_000
+const long = NOW - STALE_AFTER_MS - 60_000 /* 한 창을 넘긴 침묵 */
+
+const at = (over: Record<string, unknown> = {}) =>
+  syncVerdictOf({
+    feedState: 'attached',
+    recent: { offered: 100, rejected: 0 },
+    lastAtMs: NOW - 1_000,
+    nowMs: NOW,
+    lastUndeliveredAtMs: -1,
+    offeredTotal: 100,
+    ...over
+  } as any)
+
+/* ── 조용한 시간 ──────────────────────────────────────────────────────────── */
+
+test('★ 조용한 시간의 긴 침묵은 「유입 없음」이 아니다', () => {
+  assert.equal(at({ lastAtMs: long, quietNow: true }), 'expected-quiet')
+})
+
+test('★ 같은 침묵이 활동 시간이면 「유입 없음」이다', () => {
+  assert.equal(at({ lastAtMs: long, quietNow: false }), 'no-traffic')
+})
+
+test('★ 달력을 선언하지 않았으면 지금까지처럼 답한다 — 모르는 것을 「조용할 때」로 읽지 않는다', () => {
+  /*
+   * `quietNow` 를 주지 않은 원천이 전부 「지금은 조용한 시간」이 되면, 정말 끊긴 원천이 통째로
+   * 조용해진다. 없으면 옛 거동 그대로다.
+   */
+  assert.equal(at({ lastAtMs: long }), 'no-traffic')
+})
+
+test('★ 조용한 시간이어도 사실이 사라지고 있으면 그것이 먼저다', () => {
+  /*
+   * 버려지는 중은 **몇 시든 문제**다. 밤이라고 덮으면 밤새 새는 것을 아침에 안다.
+   */
+  const v = at({ lastAtMs: long, quietNow: true, lastUndeliveredAtMs: NOW - 1_000 })
+  assert.equal(v, 'twin-not-running')
+})
+
+test('★ 조용한 시간이어도 결선이 없으면 그것이 먼저다', () => {
+  assert.equal(at({ feedState: 'detached', lastAtMs: long, quietNow: true }), 'not-connected')
+})
+
+test('★ 한 번도 받지 않았는데 지금이 조용한 시간이면 「모른다」가 아니다', () => {
+  /*
+   * 밤에 처음 붙인 태양광 연결이 「기다린다」로 보이면, 사람이 아침까지 무엇을 기다리는지 모른다.
+   */
+  assert.equal(at({ lastAtMs: -1, recent: null, offeredTotal: 0, quietNow: true }), 'expected-quiet')
+  assert.equal(at({ lastAtMs: -1, recent: null, offeredTotal: 0 }), 'unknown')
+})
+
+test('★ 창이 비었어도 조용한 시간이면 정상이다', () => {
+  assert.equal(at({ recent: { offered: 0, rejected: 0 }, quietNow: true }), 'expected-quiet')
+  assert.equal(at({ recent: { offered: 0, rejected: 0 } }), 'no-traffic')
+})
+
+test('조용한 시간에도 받고 있으면 받는 중이다 — 침묵이 아니면 이 축이 개입하지 않는다', () => {
+  assert.equal(at({ quietNow: true }), 'syncing')
+})
+
+/* ── 원천이 선언한 주기 ──────────────────────────────────────────────────── */
+
+test('★ 15분마다 긷는 원천은 그 주기 안에서 정상이다', () => {
+  /*
+   * 창 하나(10분)로 재면 긷는 사이마다 빨갛다. 원천이 주기를 선언하면 그것으로 견준다.
+   */
+  const twelveMin = NOW - 12 * 60_000
+
+  assert.equal(at({ lastAtMs: twelveMin }), 'no-traffic', '선언이 없으면 옛 거동')
+  assert.equal(at({ lastAtMs: twelveMin, expectedSilenceMs: 20 * 60_000 }), 'syncing')
+})
+
+test('★ 선언한 주기를 넘기면 그때는 「유입 없음」이다 — 선언이 면죄부가 아니다', () => {
+  const thirtyMin = NOW - 30 * 60_000
+  assert.equal(at({ lastAtMs: thirtyMin, expectedSilenceMs: 20 * 60_000 }), 'no-traffic')
+})
+
+test('0이나 음수 주기는 선언이 아니다 — 창 하나로 돌아간다', () => {
+  for (const bad of [0, -1, NaN]) {
+    assert.equal(at({ lastAtMs: long, expectedSilenceMs: bad }), 'no-traffic', `${bad} 를 주기로 받았다`)
+  }
+})
+
+test('★ 주기와 달력은 다른 축이다 — 주기를 넘겼는데 조용한 시간이면 정상이다', () => {
+  const thirtyMin = NOW - 30 * 60_000
+  assert.equal(at({ lastAtMs: thirtyMin, expectedSilenceMs: 20 * 60_000, quietNow: true }), 'expected-quiet')
+})

package/test/ingest-idempotent.test.ts

@@ -130,3 +130,82 @@ test('트윈마다 따로 센다 — 한 트윈의 되풀이가 다른 트윈을
   const { duplicates } = b.filter([energy('inv-1', 1)])
   assert.equal(duplicates, 0)
 })
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * ★ **구별할 값이 봉투 안에 있으면 다 본다** — 골라 쓰고 나머지를 버리던 자리.
+ *
+ * ── 실측 (2026-09-05, 인티그레이션·plant 레인) ─────────────────────────────
+ * plant 이 실적 둘을 보냈는데 한 건이 저널에 안 남았다.
+ *
+ *   seq 36   quality.output   moverId EQ-CT-MWELD-01 · taskId PR-CT-WIRE-01 · goodCount 12
+ *   seq 41   quality.output   moverId EQ-CT-MWELD-01 · taskId PR-CT-WIRE-02 · goodCount  9
+ *
+ * 시각이 같았고(원본이 끝시각을 복사) 대상을 **먼저 걸리는 하나**로 골라서 `moverId` 가 이겼다.
+ * 거부가 아니라 **되풀이로 세어졌다** — 유입 장부에 `offered 5 · rejected 0 · journaled 3`.
+ *
+ * 원인이 시험 데이터였다고 해서 거동이 옳아지지 않는다. 두 봉투는 `taskId` 도 수량도 달랐고,
+ * **구별할 값이 이미 봉투 안에 있었는데 판정이 그것을 안 봤다.**
+ *
+ * ── 이 파일이 스스로 적어 둔 값 ───────────────────────────────────────────
+ *   「모르는 것을 같다고 판단하면 서로 다른 사실이 하나로 합쳐진다.
+ *    알리지 않고 잃는 것보다 두 번 세는 것이 낫다.」
+ *
+ * 지금 거동은 **알리지 않고 잃는 쪽**이었다.
+ * ════════════════════════════════════════════════════════════════════════════ */
+
+const AT_36 = '2026-09-05T06:50:00.000Z'
+const quality = (taskId: string, goodCount: number) => ({
+  eventType: 'quality.output',
+  data: { moverId: 'EQ-CT-MWELD-01', taskId, goodCount, at: AT_36 }
+})
+
+test('★ 한 설비가 두 작업을 같은 시각에 보고해도 두 사실이다 — 실제로 한 건을 잃던 그 줄', () => {
+  const a = factIdentity(quality('PR-CT-WIRE-01', 12))
+  const b = factIdentity(quality('PR-CT-WIRE-02', 9))
+
+  assert.ok(a && b, '정체를 못 만들면 거르지 않는다 — 이 검사가 뜻이 없다')
+  assert.notEqual(a, b, '작업이 다른 두 실적이 한 사실이 됐다')
+})
+
+test('★ 같은 봉투를 다시 보내면 여전히 같은 사실이다 — 넓혀도 되풀이는 잡힌다', () => {
+  /*
+   * 넓히는 것이 「되풀이를 놓친다」로 이어지지 않는다는 것이 이 변경의 근거다. 같은 봉투는 이
+   * 값들이 전부 같으므로 정체도 같다.
+   */
+  assert.equal(factIdentity(quality('PR-CT-WIRE-01', 12)), factIdentity(quality('PR-CT-WIRE-01', 12)))
+})
+
+test('★ 한 개체의 서로 다른 관측을 가른다 — EPCIS 는 그것이 정상이다', () => {
+  /*
+   * 저널 246만 건에 옛 규칙을 다시 걸어 여섯 묶음이 나왔고 전부 이 모양이었다. 한 물건이 한
+   * 순간에 입고이면서 개시일 수 있다 — 표준에서 이상한 일이 아닌데 규칙이 그 셋을 안 봤다.
+   */
+  const epc = 'urn:epc:id:sgtin:9521321.011111.1'
+  const receiving = {
+    eventType: 'epcis.ObjectEvent',
+    data: { epcList: [epc], bizStep: 'receiving', action: 'ADD', disposition: 'sellable_accessible', eventTime: AT_36 }
+  }
+  const commissioning = {
+    eventType: 'epcis.ObjectEvent',
+    data: { epcList: [epc], bizStep: 'commissioning', action: 'OBSERVE', disposition: 'reserved', eventTime: AT_36 }
+  }
+
+  assert.notEqual(factIdentity(receiving), factIdentity(commissioning), '입고와 개시가 한 사실이 됐다')
+})
+
+test('★ 참조가 달라도 갈린다 — 주체만 보고 나머지를 버리지 않는다', () => {
+  /*
+   * 「주체를 먼저 본다」는 판단 자체는 옳았다. 틀린 것은 **고르고 나머지를 버린 것**이다.
+   */
+  const one = { eventType: 'task.status', data: { taskId: 'T-1', orderId: 'order-1', at: AT_36 } }
+  const two = { eventType: 'task.status', data: { taskId: 'T-1', orderId: 'order-2', at: AT_36 } }
+
+  assert.notEqual(factIdentity(one), factIdentity(two))
+})
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  /* 가르는 값이 하나도 없으면 정체를 안 만든다(거르지 않고 통과) — 그 경계가 살아 있는지. */
+  assert.equal(factIdentity({ eventType: 'x', data: { at: AT_36 } }), undefined, '대상 없는 봉투에 정체를 만들었다')
+  assert.equal(factIdentity({ eventType: 'x', data: { taskId: 'T-1' } }), undefined, '시각 없는 봉투에 정체를 만들었다')
+  assert.ok(factIdentity(quality('T-1', 1))!.includes('task=T-1'), '작업이 정체에 안 들어갔다')
+})