@things-factory/headless-twin 10.0.18 → 10.1.0

package/test/first-envelope.test.ts

@@ -0,0 +1,153 @@
+/*
+ * 첫 봉투가 몇 번부터 시작했는지 남기는가.
+ *
+ * ── 무엇이 있었나 (2026-09-06 실측, 인티그레이션 레인이 찾음) ────────────────
+ * plant 아웃박스의 1~20 이 400 으로 거절돼 그 연결에 커서가 없었다. 다음에 온 21번이 첫 봉투로
+ * 앉으며 커서가 21 로 뛰었다.
+ *
+ * 커서가 0 이었다면 같은 21이 구멍이었다. 둘의 차이가 그 결함의 전부다. 스무 건이 구멍으로도 안
+ * 세어지고, 경고도 없고, backfill 대상도 아니었다 — backfill 은 커서부터 묻는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { firstSeqOf, seqOf, takeInSequence, withSeq } from '../server/service/reference/hook-contract.js'
+
+const item = (seq: number) => ({ seq, record: { at: '2026-09-06T00:00:00.000Z' } })
+
+test('★ 커서가 없는 연결에 21번이 오면 그 앞 20건을 못 봤다고 말한다', () => {
+  const got = takeInSequence({ items: [item(21)], scope: 'EVENTS', lastSeq: undefined })
+
+  assert.equal(got.firstUnseenBefore, 20, '못 본 개수를 안 말하면 그 사실이 아무 데도 안 남는다')
+  assert.equal(got.advancedSeq, 21)
+  assert.equal(got.gap, undefined, '첫 봉투를 구멍으로 만들지 않는다 — 거절할 근거가 없다')
+})
+
+test('★ 커서가 0 이면 같은 21번이 구멍이다 — 둘의 차이가 이 결함의 전부다', () => {
+  const got = takeInSequence({ items: [item(21)], scope: 'EVENTS', lastSeq: 0 })
+
+  assert.equal(got.gap?.expectedSeq, 1)
+  assert.equal(got.firstUnseenBefore, undefined, '구멍은 첫 봉투가 아니다')
+})
+
+test('1번부터 시작한 연결은 못 본 것이 없다 — 그 칸을 내지 않는다', () => {
+  const got = takeInSequence({ items: [item(1)], scope: 'EVENTS', lastSeq: undefined })
+
+  assert.equal(got.firstUnseenBefore, undefined, '0 을 내면 화면이 말할 것 없는 줄을 그린다')
+  assert.equal(got.advancedSeq, 1)
+})
+
+test('늦게 붙은 연결도 수만 말한다 — 손실이라고 하지 않는다', () => {
+  /*
+   * 원본이 오래 돌고 있는데 트윈을 나중에 붙이면 seq 4,712 부터 받는 것이 정상이고, 그 아래
+   * 4,711 개는 애초에 안 받기로 한 것이다. 계약은 둘을 구별할 수 없으므로 수만 낸다.
+   */
+  const got = takeInSequence({ items: [item(4712)], scope: 'EVENTS', lastSeq: undefined })
+  assert.equal(got.firstUnseenBefore, 4711)
+  assert.equal(got.advancedSeq, 4712, '늦게 붙은 것을 거절하지 않는다')
+})
+
+test('이어받는 봉투에는 그 칸이 없다', () => {
+  const got = takeInSequence({ items: [item(49)], scope: 'EVENTS', lastSeq: 48 })
+  assert.equal(got.firstUnseenBefore, undefined)
+  assert.equal(got.advancedSeq, 49)
+})
+
+test('★ 이 테스트가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  const first = takeInSequence({ items: [item(21)], scope: 'EVENTS', lastSeq: undefined })
+  const cont = takeInSequence({ items: [item(21)], scope: 'EVENTS', lastSeq: 20 })
+  assert.notEqual(first.firstUnseenBefore, cont.firstUnseenBefore, '첫 봉투와 이어받은 봉투가 같아졌다')
+})
+
+/* ── 몇 번부터 받기 시작했나를 커서에 적는다 ────────────────────────────────── */
+
+test('★ 첫 봉투의 번호를 커서에 적는다 — 「앞이 비었나」를 나중에 답하려면 이 값이 있어야 한다', () => {
+  const got = takeInSequence({ items: [item(21)], scope: 'EVENTS', lastSeq: undefined })
+  assert.equal(got.firstSeq, 21)
+
+  const cursor = withSeq({}, 'mes-line-a::EVENTS', got.advancedSeq!, got.firstSeq)
+  assert.equal(firstSeqOf(cursor, 'mes-line-a::EVENTS'), 21)
+  assert.equal(seqOf(cursor, 'mes-line-a::EVENTS'), 21)
+})
+
+test('★ 한 번 적힌 firstSeq 는 안 바뀐다 — 덮으면 「앞이 비었나」를 다시 못 묻는다', () => {
+  /*
+   * 커서가 나아간 뒤에 이 값을 만들면 그 번호는 첫 번호가 아니라 그때 마침 온 번호다.
+   */
+  let cursor = withSeq({}, 'S', 21, 21)
+  cursor = withSeq(cursor, 'S', 22, 22)
+  cursor = withSeq(cursor, 'S', 48, 48)
+
+  assert.equal(firstSeqOf(cursor, 'S'), 21, 'firstSeq 가 덮였다')
+  assert.equal(seqOf(cursor, 'S'), 48)
+})
+
+test('★ 적힌 적이 없으면 모른다고 말한다 — 0 으로 답하면 1번부터 다 받은 것으로 읽힌다', () => {
+  const old = withSeq({}, 'S', 48)
+  assert.equal(firstSeqOf(old, 'S'), undefined)
+  assert.equal(seqOf(old, 'S'), 48, '옛 커서의 번호는 그대로 읽힌다')
+})
+
+test('이어받는 봉투는 firstSeq 를 안 낸다 — 그 값을 만들 근거가 없다', () => {
+  const got = takeInSequence({ items: [item(49)], scope: 'EVENTS', lastSeq: 48 })
+  assert.equal(got.firstSeq, undefined)
+})
+
+test('1번부터 시작한 연결도 firstSeq 를 적는다 — 못 본 것이 없다는 사실도 사실이다', () => {
+  const got = takeInSequence({ items: [item(1)], scope: 'EVENTS', lastSeq: undefined })
+  assert.equal(got.firstSeq, 1)
+  assert.equal(got.firstUnseenBefore, undefined, '못 본 것이 0이면 그 칸은 안 낸다')
+})
+
+test('★ 밑에서부터 다시 받으면 그 번호가 firstSeq 가 된다 — from: 0 은 first 판정이 아니다', () => {
+  /*
+   * 실제로 났다(2026-09-06). `fillTwinScope(from: 0)` 으로 잃은 구간을 되찾았는데 커서에
+   * `firstSeq` 가 안 적혔다. 커서가 0 이라 seq 1 이 `next` 판정이었고 `first` 가 아니었기 때문이다.
+   *
+   * 그런데 우리는 실제로 1번부터 갖게 됐다. `lowestSeq` 가 그 사실을 낸다.
+   */
+  const got = takeInSequence({ items: [item(1), item(2), item(3)], scope: 'EVENTS', lastSeq: 0 })
+
+  assert.equal(got.firstSeq, undefined, '커서가 있었으므로 첫 봉투가 아니다')
+  assert.equal(got.lowestSeq, 1, '받아들인 것 중 가장 낮은 번호')
+  assert.equal(got.advancedSeq, 3)
+})
+
+test('가장 낮은 번호는 하나도 못 받으면 없다', () => {
+  const got = takeInSequence({ items: [item(9)], scope: 'EVENTS', lastSeq: 4 })
+  assert.equal(got.lowestSeq, undefined, '구멍이라 아무것도 안 받았다')
+  assert.equal(got.gap?.expectedSeq, 5)
+})
+
+/* ── 봉투의 시각 ────────────────────────────────────────────────────────────── */
+
+test('★ 시각을 안 싣는 레코드에 봉투의 시각을 얹는다 — 안 얹으면 다시 받을 때마다 새 사실이 된다', () => {
+  /*
+   * [측정함 2026-09-06] `fillTwinScope(from: 0)` 을 두 번 돌렸더니 mes-line-a 저널이 40 → 69건이
+   * 되고 중복이 27가지 생겼다. 시각을 안 싣는 레코드는 ingest 시각으로 떨어지는데 그 값이 실행할
+   * 때마다 달라서 fact identity 가 매번 바뀐다. 시각을 말하는 12건만 되풀이로 걸러졌다.
+   *
+   * plant 아웃박스는 그 시각을 봉투에 실어 보내고 있었다. 갈 자리가 없어서 버려지던 값이다.
+   */
+  const got = takeInSequence({
+    items: [{ seq: 1, record: { subjectId: 'L', decision: 'scrap' }, at: '2026-09-01T00:00:00.000Z' }],
+    scope: 'EVENTS',
+    lastSeq: 0
+  })
+  assert.equal((got.records[0] as any).at, '2026-09-01T00:00:00.000Z')
+})
+
+test('★ 레코드가 자기 시각을 말하면 그것이 이긴다 — 봉투는 「언제 보냈나」에 가깝다', () => {
+  const got = takeInSequence({
+    items: [{ seq: 1, record: { subjectId: 'L', decision: 'scrap', at: '2026-08-30T00:00:00.000Z' }, at: '2026-09-01T00:00:00.000Z' }],
+    scope: 'EVENTS',
+    lastSeq: 0
+  })
+  assert.equal((got.records[0] as any).at, '2026-08-30T00:00:00.000Z')
+})
+
+test('봉투가 시각을 안 말하면 레코드를 그대로 둔다 — 없는 값을 만들지 않는다', () => {
+  const rec = { subjectId: 'L', decision: 'scrap' }
+  const got = takeInSequence({ items: [{ seq: 1, record: rec }], scope: 'EVENTS', lastSeq: 0 })
+  assert.equal(got.records[0], rec, '새 객체를 만들 이유가 없다')
+})

package/test/fold-shift-dst.test.ts

@@ -0,0 +1,110 @@
+/*
+ * Folding a span that crosses a daylight-saving transition.
+ *
+ * ── Why this is worth a test ───────────────────────────────────────────────
+ * `utcOffsetMinutes` on the model is one number, resolved when the host starts the twin.
+ * Folding walks a past span, so a year of facts gets read with whatever offset happened to
+ * be current at start — and a year holds two transitions. Facts after one land an hour off
+ * and are counted into the neighbouring shift. Nothing errors; shift performance is simply
+ * wrong, and plausible.
+ *
+ * `America/Tijuana` is already in this deployment's data (PST -480 / PDT -420), so this is
+ * not a hypothetical.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { foldKpi } from '../server/engine/kpi-fold.js'
+
+/* Two shifts that between them cover the day, so a misread hour lands in the other one. */
+const SHIFTS = [
+  { id: 'day', fromTime: '06:00', toTime: '18:00' },
+  { id: 'night', fromDayOffset: 0, fromTime: '18:00', toDayOffset: 1, toTime: '06:00' }
+] as any[]
+
+/* Tijuana: PDT (-420) in July, PST (-480) in December. */
+const SUMMER = Date.UTC(2026, 6, 15, 13, 30) //  06:30 local under -420 → day shift
+const WINTER = Date.UTC(2026, 11, 15, 13, 30) // 05:30 local under -480 → night shift
+
+/*
+ * The same rule the host uses (`utcOffsetOf`), written out here because that function lives
+ * beside code the test runner cannot load. Kept small and checked by its own test below, so a
+ * drift in it does not quietly turn the rest of this file green.
+ */
+function offsetAt(atMs: number): number | undefined {
+  const name = new Intl.DateTimeFormat('en-US', { timeZone: 'America/Tijuana', timeZoneName: 'longOffset' })
+    .formatToParts(new Date(atMs))
+    .find(p => p.type === 'timeZoneName')?.value
+
+  const m = /^GMT([+-])(\d{1,2}):(\d{2})$/.exec(name ?? '')
+
+  return m ? (m[1] === '-' ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) : undefined
+}
+
+/*
+ * A completed task is a transition, not one row — the fold counts throughput at completion
+ * and needs the earlier states to have a lead time to measure.
+ */
+const doneAt = (ms: number, id: string): any[] =>
+  ['created', 'in-progress', 'completed'].map((status, i) => ({
+    eventType: 'task.status',
+    eventTime: new Date(ms - (2 - i) * 30_000).toISOString(),
+    payload: { data: { taskId: id, status } }
+  }))
+
+function shiftsOf(events: any[], options: any) {
+  const out = foldKpi(events, { fromMs: Date.UTC(2026, 0, 1), toMs: Date.UTC(2027, 0, 1) } as any, {
+    groupBy: 'shift',
+    shifts: SHIFTS,
+    ...options
+  } as any)
+
+  return (out as any)?.groups?.items?.map((g: any) => g.key) ?? []
+}
+
+test('the probe itself reads Tijuana as -420 in July and -480 in December', () => {
+  /* If this drifts, the rest of the file is measuring nothing. */
+  assert.equal(offsetAt(SUMMER), -420)
+  assert.equal(offsetAt(WINTER), -480)
+})
+
+test('a fixed offset puts a December fact in the wrong shift — the defect', () => {
+  /*
+   * Both facts are 13:30 UTC. Read with the summer offset the December one looks like
+   * 06:30 local and lands on the day shift, when locally it was 05:30 and belongs to the
+   * night shift.
+   */
+  const keys = shiftsOf([...doneAt(WINTER, 'w')], { utcOffsetMinutes: -420 })
+
+  assert.deepEqual(keys, ['day'])
+})
+
+test('offsetAt resolves per fact, so the December fact lands on the night shift', () => {
+  const keys = shiftsOf([...doneAt(WINTER, 'w')], { utcOffsetMinutes: -420, offsetAt })
+
+  assert.deepEqual(keys, ['night'])
+})
+
+test('the same span read per instant splits across both shifts, not one', () => {
+  const keys = shiftsOf([...doneAt(SUMMER, 's'), ...doneAt(WINTER, 'w')], { utcOffsetMinutes: -420, offsetAt }).sort()
+
+  assert.deepEqual(keys, ['day', 'night'])
+})
+
+test('offsetAt returning undefined falls back to the number rather than to UTC', () => {
+  /*
+   * Not knowing the offset for an instant is not the same as the instant being UTC.
+   * Falling through to the declared number keeps the previous behaviour instead of
+   * silently asserting Greenwich.
+   */
+  const keys = shiftsOf([...doneAt(WINTER, 'w')], { utcOffsetMinutes: -420, offsetAt: () => undefined })
+
+  assert.deepEqual(keys, ['day'])
+})
+
+test('no offset at all still folds, reading times as UTC as the contract states', () => {
+  const keys = shiftsOf([...doneAt(WINTER, 'w')], {})
+
+  /* 13:30 UTC is inside 06:00-18:00. */
+  assert.deepEqual(keys, ['day'])
+})

package/test/home-in-area.test.ts

@@ -0,0 +1,90 @@
+/*
+ * **설비는 자리에도 구역에도 설 수 있다.**
+ *
+ * ── 실물 (2026-09-06) ───────────────────────────────────────────────────────
+ * `EQ-CAM-SHOWER-01`(에어샤워)이 `LINE-CAM` 이라는 **구역**에 딸려 있다. 라인 전체에 붙는 설비는
+ * 자리 하나를 고를 수 없고, 그것이 정상이다.
+ *
+ * 그런데 인제스트가 그 참조를 **「끊어졌다」고 경고**했다. 자리 목록에서만 찾았기 때문이다.
+ *
+ * ```
+ * unresolved-reference
+ * equipment.homeLocation points at something that is not in this twin (EQ-CAM-SHOWER-01→LINE-CAM)
+ * ```
+ *
+ * 계약이 그 갈림을 위해 `homeLocationKind = 'location' | 'area'` 를 두었는데 **아무도 안 채우고
+ * 있었다** — 선언만 있고 읽는 쪽도 쓰는 쪽도 0곳이었다.
+ *
+ * 짐작하지 않는다. 마스터가 이미 `role` 로 자리와 구역을 가르고 있으므로 그것을 읽는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { masterToTwin } from '../server/service/reference/reference-master.ts'
+
+const master = (): any => ({
+  source: 'm',
+  system: 'mes',
+  siteName: 'S',
+  space: { spaceId: 'm-site', width: 100, depth: 60, unit: 'm' },
+  locations: [
+    { id: 'ST-1', role: 'location', type: 'weld-station', capacity: 1 },
+    { id: 'LINE-CAM', role: 'area', type: 'line' }
+  ],
+  equipment: [
+    { id: 'EQ-WELD-1', kind: 'welder', homeLocationId: 'ST-1' },
+    { id: 'EQ-CAM-SHOWER-01', kind: 'air-shower', homeLocationId: 'LINE-CAM' }
+  ]
+})
+
+const eq = (model: any, id: string) => model.equipment.find((e: any) => e.id === id)
+
+test('★ 구역에 선 설비는 homeLocationKind 로 그것을 말한다', () => {
+  const { model } = masterToTwin(master())
+  const shower = eq(model, 'EQ-CAM-SHOWER-01')
+
+  assert.equal(shower.homeLocation, 'LINE-CAM')
+  assert.equal(shower.homeLocationKind, 'area', '구역인 것을 안 말하면 읽는 쪽이 자리로 읽는다')
+})
+
+test('★ 자리에 선 설비는 그 칸을 안 만든다 — 계약의 기본값이 location 이다', () => {
+  /*
+   * 없는 칸을 만들면 화면이 그것을 그리고, 「자리」라는 당연한 말이 모든 줄에 붙는다.
+   * `homeOf()` 가 없을 때 `'location'` 을 내는 것이 그래서다.
+   */
+  const { model } = masterToTwin(master())
+  const welder = eq(model, 'EQ-WELD-1')
+
+  assert.equal(welder.homeLocation, 'ST-1')
+  assert.equal('homeLocationKind' in welder, false)
+})
+
+test("★ role 이 'both' 면 자리다 — 구역으로 만들지 않는다", () => {
+  /*
+   * `both` 는 그 줄이 자리 목록에도 구역 목록에도 들어간다는 뜻이다. 설비가 그것을 가리키면
+   * **자리 쪽이 이긴다** — 자리는 설비가 실제로 서는 지점이고, 구역은 그것을 담는 넓이다.
+   */
+  const m = master()
+  m.locations = [{ id: 'CELL-1', role: 'both', type: 'cell', capacity: 1 }]
+  m.equipment = [{ id: 'EQ-1', kind: 'welder', homeLocationId: 'CELL-1' }]
+
+  const { model } = masterToTwin(m)
+  assert.equal('homeLocationKind' in eq(model, 'EQ-1'), false)
+})
+
+test('기준 자리가 없는 설비는 그 칸도 없다', () => {
+  const m = master()
+  m.equipment = [{ id: 'EQ-FREE', kind: 'agv' }]
+  const { model } = masterToTwin(m)
+  assert.equal('homeLocationKind' in eq(model, 'EQ-FREE'), false)
+})
+
+test('★ 이 테스트가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  const { model } = masterToTwin(master())
+  assert.equal(model.equipment.length, 2, '설비를 하나도 안 읽었다')
+  assert.notEqual(
+    eq(model, 'EQ-CAM-SHOWER-01').homeLocationKind,
+    eq(model, 'EQ-WELD-1').homeLocationKind,
+    '구역에 선 설비와 자리에 선 설비가 같아졌다'
+  )
+})

package/test/hook-rejected-shape.test.ts

@@ -0,0 +1,86 @@
+/*
+ * 떨어진 것에 봉투 id 가 실리나.
+ *
+ * ── 왜 필요한가 (2026-09-07 측정) ───────────────────────────────────────────
+ * 훅 응답의 떨어진 목록이 `{ record, errors }` 였고, plant 은 그것을 **봉투 id 문자열 목록**으로
+ * 읽고 있었다.
+ *
+ * ```
+ * headless-twin  rejected: { record, errors }[]        객체 배열
+ * plant          "rejected is a list of envelope ids"  문자열 배열
+ * ```
+ *
+ * `Array.isArray` 는 통과하니 그쪽 guard 도 안 걸렸다. id 를 맞추는데 객체라 하나도 안 맞고
+ * **묶음 전체가 「보냈음」으로 찍혔다** — 422 와 `ok: false` 를 보냈는데 재시도 0 · 오류 없음이었다.
+ *
+ * 우리가 말했는데 상대가 못 알아듣는 모양이면, 말한 것이 아니다.
+ *
+ * 이 시험은 **모양**을 본다. 값이 흐르는지는 다른 시험이 보고, 여기서는 보내는 쪽이 자기 행을 찾을 수
+ * 있는 열쇠가 실리는지만 본다.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { rejectedForCaller } from '../server/service/reference/hook-rejected.js'
+
+const bad = { orderId: 'WO-1' }
+const worse = { orderId: 'WO-2' }
+const ERRORS = ['order: at 없음/형식 오류']
+
+test('봉투 id 를 아는 것은 id 로 나간다 — 보내는 쪽이 그 행만 표시할 수 있다', () => {
+  const out = rejectedForCaller([{ record: bad, errors: ERRORS }], [{ record: bad, eventId: 'evt-1' }])
+
+  assert.deepEqual(out, [{ eventId: 'evt-1', errors: ERRORS }])
+})
+
+test('id 를 모르면 레코드를 그대로 싣는다 — 빈 id 를 넣지 않는다', () => {
+  /*
+   * 빈 id 를 실으면 보내는 쪽이 아무 행도 못 찾으면서 「알았다」고 여긴다. 그때는 무엇이 떨어졌는지
+   * 보여 주는 것이 유일한 답이다.
+   */
+  const out = rejectedForCaller([{ record: bad, errors: ERRORS }], [{ record: bad }])
+
+  assert.deepEqual(out, [{ record: bad, errors: ERRORS }])
+})
+
+test('짝은 객체 동일성으로 짓는다 — 같은 모양의 레코드 둘이 서로의 id 를 가져가지 않는다', () => {
+  const twinA = { orderId: 'SAME' }
+  const twinB = { orderId: 'SAME' }
+  const out = rejectedForCaller(
+    [{ record: twinB, errors: ERRORS }],
+    [
+      { record: twinA, eventId: 'evt-A' },
+      { record: twinB, eventId: 'evt-B' }
+    ]
+  )
+
+  assert.deepEqual(out, [{ eventId: 'evt-B', errors: ERRORS }], '값으로 비교하면 evt-A 가 나온다')
+})
+
+test('여러 건이 각자의 id 로 나간다', () => {
+  const out = rejectedForCaller(
+    [
+      { record: bad, errors: ERRORS },
+      { record: worse, errors: ['다른 까닭'] }
+    ],
+    [
+      { record: bad, eventId: 'evt-1' },
+      { record: worse, eventId: 'evt-2' }
+    ]
+  )
+
+  assert.deepEqual(out, [
+    { eventId: 'evt-1', errors: ERRORS },
+    { eventId: 'evt-2', errors: ['다른 까닭'] }
+  ])
+})
+
+test('빈 문자열·공백 id 는 없는 것으로 본다 — 아무 행도 못 찾는 열쇠다', () => {
+  assert.deepEqual(rejectedForCaller([{ record: bad, errors: ERRORS }], [{ record: bad, eventId: '   ' }]), [
+    { record: bad, errors: ERRORS }
+  ])
+})
+
+test('떨어진 것이 없으면 빈 목록이다', () => {
+  assert.deepEqual(rejectedForCaller([], [{ record: bad, eventId: 'evt-1' }]), [])
+})

package/test/hook-response-sum.test.ts

@@ -0,0 +1,193 @@
+/*
+ * Does the reply's own arithmetic close.
+ *
+ * ── Why this exists (2026-09-07) ───────────────────────────────────────────
+ * The contract now declares the response a sender reads, and the reason it had to is that a
+ * sender guessed instead: operato-plant read `rejected` as a list of envelope id strings, the
+ * receiver sent `{record, errors}`, `Array.isArray` passed on both, and a batch of three was
+ * stamped delivered while one envelope never landed (mes_outbox_events seq 178 — SENT,
+ * attempts 0, no error).
+ *
+ * `offered` is the field that makes that catchable without reading the rejection list at all:
+ *
+ *   offered === applied + duplicates + rejected.length + vocabulary
+ *
+ * ── What this file is really guarding ──────────────────────────────────────
+ * The first version of that sum left `vocabulary` out, and it was wrong. Vocabulary elements are
+ * counted in `offered` and deliberately kept out of the other three — they set state and must
+ * never reach the journal, because they carry no time axis. So every batch carrying one would
+ * have failed a sender's check, the warning would have been ignored within a week, and the real
+ * loss would have been ignored with it.
+ *
+ * The integration lane found that by looking for a counterexample rather than a confirmation,
+ * and had a measured one: 32 distinct facts reconciled as 29 journal + 2 rejected + 1 vocabulary.
+ *
+ * The count already existed — `liveIngest` has returned `vocabulary` all along — and this
+ * boundary dropped it, because the callback was typed as `IngestResult` and the field was not on
+ * it. A declared field nobody fills is the same defect one layer over, so what is asserted here
+ * is that a number handed to `ingest` arrives in the reply, and that the sum closes on a batch
+ * where it is not zero.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { WEBHOOK_STATUS } 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 = 'sum-source'
+const TWIN = 'twin-a'
+const SECRET = 'shared-secret'
+
+/** Hands every item straight through — this file is about the counts, not about translation. */
+const ADAPTER_TYPE = 'test-sum-push'
+if (!getAdapter(ADAPTER_TYPE)) {
+  registerAdapterType({
+    type: ADAPTER_TYPE,
+    label: 'sum push (test)',
+    handleInbound: (_cfg: any, _site: any, body: any) => ({ items: body?.items ?? [] })
+  } as any)
+}
+
+function makeStore(): HookStore {
+  const row = {
+    id: 'ref-1',
+    source: SOURCE,
+    adapterType: ADAPTER_TYPE,
+    connectionConfig: { hookSecret: SECRET },
+    scopeSpec: { produced: [{ siteId: 'site-a', instanceId: TWIN }] }
+  }
+  return {
+    load: async (domainId: string, source: string) => (domainId === DOMAIN && source === SOURCE ? row : null),
+    saveCursor: async () => {}
+  } as any
+}
+
+/** `count` unnumbered items — no `scope`, so sequence checking stays out of the way. */
+function items(count: number) {
+  return Array.from({ length: count }, (_v, i) => ({ record: { moverId: `eq-${i}`, kind: 'press', status: 'idle' } }))
+}
+
+function push(count: number, ingest: any) {
+  return handleHook({
+    domainId: DOMAIN,
+    source: SOURCE,
+    instanceId: TWIN,
+    headers: { 'x-twin-hook-secret': SECRET },
+    body: { items: items(count) },
+    nowMs: Date.parse('2026-09-07T02:00:00.000Z'),
+    ingest,
+    store: makeStore()
+  })
+}
+
+/** What the sender is told to check. Written once so every case below reads the same way. */
+function closes(body: any) {
+  return body.offered === body.applied + body.duplicates + (body.rejected?.length ?? 0) + body.vocabulary
+}
+
+test('the sum closes when everything was applied', async () => {
+  const out = await push(3, (_id: string, r: unknown[]) => ({ applied: r.length, duplicates: 0, rejected: [] }))
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.offered, 3)
+  assert.equal(out.body.vocabulary, 0)
+  assert.ok(closes(out.body), JSON.stringify(out.body))
+})
+
+test('the sum closes when a batch carried vocabulary — this is the case that failed', async () => {
+  /*
+   * Three offered: two events seated, one vocabulary element. Without `vocabulary` in the reply
+   * the sender sees `3 - 2 - 0 - 0 = 1` and calls it a loss, on traffic that is entirely correct.
+   */
+  const out = await push(3, () => ({ applied: 2, duplicates: 0, rejected: [], vocabulary: 1 }))
+
+  assert.equal(out.body.offered, 3)
+  assert.equal(out.body.applied, 2)
+  assert.equal(out.body.vocabulary, 1, 'the count exists in liveIngest; this boundary must carry it')
+  assert.ok(closes(out.body), JSON.stringify(out.body))
+})
+
+test('a batch that is only vocabulary is not read as a dead twin', async () => {
+  /*
+   * This is what the sum test found, and it was a live defect rather than a missing field.
+   *
+   * The 503 branch inferred "the twin is not running live" from applied, duplicates and rejected
+   * all being zero. A vocabulary-only batch is exactly that shape and yet everything in it
+   * landed, so the receiver answered 503 to correct traffic — and a 503 means hold and retry, so
+   * the sender would have re-sent that batch every thirty seconds indefinitely.
+   *
+   * An absence is not a cause. The fourth term is what tells the two apart.
+   */
+  const out = await push(2, () => ({ applied: 0, duplicates: 0, rejected: [], vocabulary: 2 }))
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok, 'zero events applied is not a twin that stopped')
+  assert.equal(out.body.applied, 0)
+  assert.equal(out.body.vocabulary, 2)
+  assert.ok(closes(out.body), 'zero applied is not zero received')
+})
+
+test('a dead twin is still reported as one — the fourth term did not loosen the check', async () => {
+  /*
+   * Breaking the case above must not cost the case it was guarding. Nothing applied and no
+   * vocabulary either is the real "nothing landed", and it has to keep answering 503: a 200 there
+   * would have the sender mark those facts sent and drop them.
+   */
+  const out = await push(2, () => ({ applied: 0, duplicates: 0, rejected: [], vocabulary: 0 }))
+
+  assert.equal(out.status, WEBHOOK_STATUS.notLive)
+  assert.equal(out.body.retryAfterMs, 30_000, 'hold and come back, do not drop')
+})
+
+test('the sum closes on a partial — the rejected list is a term in it', async () => {
+  const out = await push(3, (_id: string, r: unknown[]) => ({
+    applied: 1,
+    duplicates: 0,
+    rejected: [{ record: r[1], errors: ['no inputQuantityList'] }],
+    vocabulary: 1
+  }))
+
+  assert.equal(out.status, WEBHOOK_STATUS.partial, '422 is what a sender must not resend')
+  assert.equal(out.body.rejected?.length, 1)
+  assert.ok(closes(out.body), JSON.stringify(out.body))
+})
+
+test('duplicates are a term too — a resend is normal here, not a loss', async () => {
+  const out = await push(4, () => ({ applied: 1, duplicates: 3, rejected: [] }))
+
+  assert.equal(out.body.duplicates, 3)
+  assert.ok(closes(out.body))
+})
+
+test('an ingest that says nothing about vocabulary still reports the term', async () => {
+  /*
+   * `vocabulary` is optional on `IngestResult` so a caller that does not count it need not claim
+   * none. The reply must still carry the term: a field that appears only sometimes leaves the
+   * sender unable to tell "none" from "this receiver does not count it", which is the same
+   * ambiguity that made `rejected` guessable.
+   */
+  const out = await push(2, () => ({ applied: 2, duplicates: 0, rejected: [] }))
+
+  assert.equal(out.body.vocabulary, 0)
+  assert.ok('vocabulary' in (out.body as any))
+})
+
+test('seq 178 as it would read now — three offered, two applied', async () => {
+  /*
+   * The real batch: one of the three had no `inputQuantityList` and the kernel was right to
+   * refuse it. What went wrong was that the sender could not read the refusal, so it marked all
+   * three sent. The sum alone says otherwise, whatever shape the rejection list is in.
+   */
+  const out = await push(3, (_id: string, r: unknown[]) => ({
+    applied: 2,
+    duplicates: 0,
+    rejected: [{ record: r[2], errors: ['transformation: inputQuantityList is empty'] }]
+  }))
+
+  assert.equal(out.body.offered, 3)
+  assert.equal(out.body.applied, 2)
+  assert.equal(out.body.offered - out.body.applied - out.body.duplicates - out.body.vocabulary, 1)
+  assert.ok(closes(out.body), 'and the missing one is accounted for by the rejected list')
+})