[DONE] 정리 4단계 PR 11 — MQTT 벡터가 시험 브로커를 거쳐 토픽과 역할을 가상 패널에 돌려 보고 check:mqtt-vectors 가 생긴다

[patternflow-bot]

ops / https://claude.ai/code/session_01Bqrhsc29GLhQvHPem3UshZ

정리 4단계 계획서 표의 PR 11 이다. MQTT 계약의 토픽 표와 두 역할을 벡터 아홉 개로 적고, 벡터마다 시험 브로커를 하나씩 띄워 가상 패널에 돌려 보는 check:mqtt-vectors 를 더했다. 머지되면 mqtt-spec.md 의 문장이 바뀌거나 가상 패널이 그 문장과 어긋날 때 PR 마다 drift 검사가 빨개진다.

좋아지는 것: 없음

할 일

• 계획서 PR 11 행(k11)과 D6~D12, PR 3([DONE] 정리 4단계 PR 3 — 계약 벡터를 적는 꼴이 정해지고, 다섯 벡터 묶음이 같이 쓸 재생기가 생긴다 #71), PR 9([DONE] 정리 4단계 PR 9 — 가상 패널이 MQTT 브로커에 붙는다: 역할, 채널, 토픽, 8초 스냅숏 #74), PR 10([DONE] 정리 4단계 PR 10 — 가상 패널이 /api/mqtt 로 브로커와 역할을 받고, status 에 MQTT 세 칸을 보인다 #77)이 k11 에 남긴 말을 읽는다
• web/scripts/drift/_broker.ts: 연결, 구독, 발행, retain 만 하는 MQTT 3.1.1 브로커와 mqtt Sender
• web/scripts/drift/mqtt-vectors.ts: replay("docs/mqtt-vectors", { mqtt })
• docs/mqtt-vectors/topics-*.json 아홉 개와 README.md
• 300줄 안: +293
• 열 번 연달아, 그리고 4코어에 여덟 개씩 세 번 나란히(24번) 돌려 다 통과
• 일부러 깨뜨린 실행 둘(패널 하나, 스펙 하나), 되돌림
• typecheck, lint, check:drift, 링크, 잠금, 글투, doc-map
• dev 에 들어온 PR 6([DONE] 정리 4단계 PR 6 — REST 벡터가 status, params, sleep 를 가상 패널에 돌려 보고 check:rest-vectors 가 생긴다 #76)과 PR 13([DONE] 정리 4단계 PR 13 — 가상 패널이 OSC 로 호스트와 주고받는다: 핑과 알림, 하트비트, 노브, 패턴 #78)을 merge 하고 다시 돌렸다. README 는 이제 dev 에 있는 docs/rest-api-vectors/README.md 를 링크한다
• 이 PR 의 CI: ffb5d2a 에서 Drift checks(38754668255), Docs point at files that exist(38754668222), Web CI(38754668331) 셋 다 success
• [DONE] 직전 dev 를 다시 받아 본다: 975433a 그대로라 merge 할 것이 없다

한 일

_broker.ts 는 벡터마다 127.0.0.1 의 빈 포트에 브로커를 하나 띄운다. CONNECT 엔 CONNACK, SUBSCRIBE 엔 QoS 0 SUBACK 과 그 토픽에 남은 retain 메시지, PINGREQ 엔 PINGRESP, DISCONNECT 엔 끊기다. 토픽은 글자 그대로만 맞춘다(와일드카드 없음, mqtt-spec.md 12행). PUBLISH 는 그 토픽을 구독한 연결마다 retain 비트를 끄고 보내고, retain 이면 브로커에 남긴다. 빈 retain 은 남은 것을 지운다. mqtt.ts 의 framing 을 가져다 쓰지 않고 따로 짰다.

Sender 의 open() 은 POST /api/mqtt 에 host 와 port 만 보낸다. 패널은 Broadcast 에 역할 off 로 남아 아무 데도 걸지 않는다. 역할은 벡터가 첫 스텝에서 고르고(POST /api/mqtt?role=subscriber), 패널이 다음 프레임에 걸므로 그다음 스텝은 wait 다. send 는 { topic, payload } 를, "retain": true 면 남기면서, 구독자에게 보낸다. heard 는 패널이 보낸 PUBLISH 마다 { topic, payload, retain } 이다. settle() 은 /api/mqtt 의 state 가 connecting 이 아니고, setImmediate 세 번과 HTTP 왕복 한 번 동안 브로커를 오간 바이트 수가 그대로일 때 끝난다. 2초를 넘기면 던진다.

TCP 에서 두 번 막혔다. 처음엔 연결 직후 메시지가 넷쯤 사라졌다. 브로커가 SUBACK 열한 개를 한꺼번에 쓰면 Nagle 규칙 때문에 첫 것 뒤가 패널 쪽 커널의 지연 ACK(리눅스 40 ms)를 기다렸고, 벡터가 보낸 PUBLISH 가 그 뒤에 섰다. 패널은 CONNACK 4바이트와 SUBACK 둘(10바이트)만 받고, 브로커가 그 뒤에 쓴 110바이트는 실제 시간 40 ms 뒤에야 닿았다. 브로커 소켓에 setNoDelay(true) 를 켰다. 반대쪽도 같았다. mqtt.ts 의 소켓은 Nagle 이 켜져 있어, 발행자가 잇달아 보내는 두 번째 메시지가 브로커 쪽 커널의 지연 ACK 를 기다렸다. 그 파일은 PR 9 행이라 고치지 않았다. 브로커가 패널의 PUBLISH 마다 PINGRESP(2바이트)를 돌려보내 ACK 가 바로 가게 했다. 패널은 PINGRESP 를 keepalive 기다림을 푸는 것 말고는 무시한다.

벡터 아홉, 저마다 스펙 한 문장이다.

• topics-sleep.json: 32행 「Publishing 1 to <prefix>/sleep …」. docs/contract-vectors.md 의 MQTT 예에 역할과 연결 스텝을 더했다.
• topics-sleep-words.json: 26행, 낱말 열(1, 0, on, off, true, false, sleep, wake, toggle 두 번)마다 status 와 sleep/state.
• topics-sleep-state.json: 27행. 구독자로 붙자 0 하나만, REST 로 재우자 1, 발행자로 다시 붙자 1. 셋 다 retain 없이.
• topics-knob.json: 39행. knob/2 에 0, 5, 5, -2, 25 를 보내면 패턴이 받은 클릭 합이 0, 5, 5, -2, 25.
• topics-param.json: 23행. param/3 을 750, 1000, 0 으로 잡고 빈 페이로드로 놓는다.
• topics-pattern.json: 24행. 이름 Wave Saw, Origin, slug wave_saw.
• topics-publisher-ignores.json: 41행. 발행자에게 knob, param, pattern 을 보내도 패널은 그대로이고 아무것도 보내지 않는다.
• topics-either-role.json: 32행. 구독자와 발행자 둘 다 message 배너를 띄우고(GET /vp/mqtt), 발행자가 sleep 을 따른다.
• topics-publisher.json: 13행. 손이 돌린 K2 의 누적 클릭 -3, -2 와 고른 패턴이 나간다.

증거

로컬, web/:

$ git diff --stat origin/dev...HEAD
 docs/mqtt-vectors/README.md                     |  13 +++
 docs/mqtt-vectors/topics-either-role.json       |  17 ++++
 docs/mqtt-vectors/topics-knob.json              |  19 ++++
 docs/mqtt-vectors/topics-param.json             |  17 ++++
 docs/mqtt-vectors/topics-pattern.json           |  15 +++
 docs/mqtt-vectors/topics-publisher-ignores.json |  16 +++
 docs/mqtt-vectors/topics-publisher.json         |  13 +++
 docs/mqtt-vectors/topics-sleep-state.json       |  13 +++
 docs/mqtt-vectors/topics-sleep-words.json       |  19 ++++
 docs/mqtt-vectors/topics-sleep.json             |  11 ++
 web/scripts/drift/_broker.ts                    | 130 ++++++++++++++++++++++++
 web/scripts/drift/mqtt-vectors.ts               |  10 ++
 12 files changed, 293 insertions(+)

$ npm run typecheck                    # exit 0
$ npm run lint -- --max-warnings=0     # exit 0
$ npm run check:mqtt-vectors
docs/mqtt-vectors/topics-either-role.json: same
docs/mqtt-vectors/topics-knob.json: same
docs/mqtt-vectors/topics-param.json: same
docs/mqtt-vectors/topics-pattern.json: same
docs/mqtt-vectors/topics-publisher-ignores.json: same
docs/mqtt-vectors/topics-publisher.json: same
docs/mqtt-vectors/topics-sleep-state.json: same
docs/mqtt-vectors/topics-sleep-words.json: same
docs/mqtt-vectors/topics-sleep.json: same
passed   mqtt-vectors
# 한 번에 1.2~1.4 s. 열 번 연달아 exit 0. 4코어에 여덟 개씩 나란히 세 번, 24번 다 exit 0.

# 깨뜨린 실행, 패널: mqtt.ts 의 sim.nudge(i, count - from) 를 sim.nudge(i, count) 로. git checkout 으로 되돌렸다
docs/mqtt-vectors/topics-knob.json: drift
  only in the vector: step 08 input.given.deltas[1] 5, step 10 input.given.deltas[1] -2, step 12 input.given.deltas[1] 25
  only in the panel: step 08 input.given.deltas[1] 10, step 10 input.given.deltas[1] 8, step 12 input.given.deltas[1] 33
failed   mqtt-vectors

# 깨뜨린 실행, 스펙: mqtt-spec.md 41행 "ignores them silently" 를 "ignores them without a word" 로. 되돌렸다
docs/mqtt-vectors/topics-publisher-ignores.json: drift
  only in the vector: says docs/mqtt-spec.md
  only in the panel: says not in docs/mqtt-spec.md
failed   mqtt-vectors

# dev merge 뒤(PR 6, PR 13 이 들어온 4f247e1)
$ npm run check:drift      # passed bom, bom-schematic, changelog, editions, features, links-absolute, markers, mqtt-vectors, presets, rest-vectors, shared, virtual-panel; skipped roadmap
$ npm run check:mqtt-vectors   # 다섯 번 연달아, 여덟 개 나란히 한 번, 다 exit 0
$ python3 .github/scripts/check_links.py
all 722 relative links resolve
$ npm run check:human-lock
check:human-lock: no locked words changed
$ npm run check:voice
read: 149 added lines in 3 files
check:voice: nothing found
$ git fetch --tags && npm run doc-map          # CSV 는 git checkout 으로 되돌렸다
1108 links from 221 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
1366 Korean/English pairs → docs/investigations/2026-10-doc-parity.csv
7 en-short, 18 ko-short, 1 missing-ko, 1340 ok

doc-map 에 이 PR 의 새 줄은 넷이고 다 닿는다. README 에서 docs/mqtt-spec.md, docs/contract-vectors.md, tools/virtual-panel/README.md, docs/rest-api-vectors/README.md 로.

Nagle 을 찾은 실행. 브로커와 패널 소켓에 로그를 잠깐 달았다(커밋하지 않음). 구독자로 붙인 뒤 sleep 을 20 ms 마다 1, 0, 1, 0, 1 로 보냈다:

broker wrote 4 32 … bytesWritten 4          ← CONNACK
panel data 4 32 up false now 20
broker wrote 5 144 … bytesWritten 9 … 59    ← SUBACK 열한 개를 한 번에
panel data 10 144 up true now 20            ← 둘만 닿았다
broker wrote 22 48 … bytesWritten 81 … 169  ← sleep 다섯
1 40 run false 1
0 60 run false 1
1 80 run false 1
0 100 run false 1
1 120 run false 1                            ← 패널은 하나도 받지 못했다

GitHub, 이 PR: ffb5d2a 에서 「Drift checks / check」(38754668255, PF_DRIFT_STRICT=1, human-lock 포함), 「Docs point at files that exist / check」(38754668222), 「Web CI / build」(38754668331)가 success. dev merge 전 5c458ae 의 strict drift 로그에도 passed mqtt-vectors 가 있다(job 116487316083).

실행법

cd web && npm ci
npm run check:mqtt-vectors

가정

• 기준 브랜치는 dev(머리말). 표가 PR 11 에 적은 네 자리(docs/mqtt-vectors/README.md, docs/mqtt-vectors/topics-*.json, _broker.ts, mqtt-vectors.ts)에만 더했다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV, mqtt.ts, mqtt-http.ts, _vectors.ts, docs/contract-vectors.md 는 안 고쳤다. 라벨은 앞 PR 들처럼 달지 않았다.
• Sender 는 브로커와 같은 _broker.ts 에 둔다. D10 은 스위트가 송신기를 자기 _ 파일에 둔다고 하고, 표가 k11 에 준 _ 파일이 이것 하나다.
• 역할은 Sender 가 아니라 벡터가 HTTP 스텝으로 고른다. Sender 가 정하면 벡터만 읽어서는 어느 역할인지 모른다. 스펙 13행의 POST /api/mqtt?role=subscriber 그대로다.
• 연결하는 wait 마다 mqttConnected: true 를 본다. 붙지 못했을 때 벡터가 뒤의 엉뚱한 줄이 아니라 그 자리에서 실패한다.
• PINGRESP 를 돌려보내는 건 실제 브로커가 하지 않는 일이다. 다른 길은 settle() 이 실제 시간으로 40 ms 넘게 기다리는 것이다. 지연 ACK 는 운영체제마다 달라 고르지 않았다. mqtt.ts 가 setNoDelay(true) 를 켜면 필요 없어진다(for another k).
• knob 벡터는 먼저 0 을 보내고 한 번 기다린다. 처음 받은 수를 무엇과 비교하는지 스펙이 말하지 않아서다(D8). 0 이 기준이면 어느 읽기로도 움직임이 0 이다. 그 뒤 wait 는 한 프레임에 온 둘을 합치는 구현(펌웨어의 coalesce)에서도 같은 결과가 나오게 둔 것이다.
• 발행자가 보내는 pattern 의 페이로드는 "<string>" 이다. 24행이 「display name or slug」 라 이름만 맞다고 할 수 없다. 가상 패널은 이름을 보낸다.
• 발행자가 knob, param, pattern 을 무시하는 건 그 토픽을 구독하지 않는 것으로도 맞는다. 구독하고 무시하는 패널과 구독하지 않는 패널은 브로커 너머에서 같아 보여 벡터가 가르지 않는다. 깨뜨린 첫 시도(발행자가 knob 을 따르게 한 것)가 통과한 까닭이고, 그래서 knob 차이를 깨뜨린 실행을 적었다.
• 하지 않은 것은 k12 몫이다. 채널 1~4 와 Live, Broadcast 에 스냅숏이 없는 것, 스냅숏의 param, message 의 retain(broadcast: yes · channels: no), /api/mqtt. README 의 마지막 문단이 벡터 없는 곳을 적는다(Director 토픽, 다시 거는 간격, 로그인 거절).
• 스크린샷은 없다. 화면이 바뀌는 PR 이 아니다.
• firmware/ 와 web/src/ 를 건드리지 않아 build.sh all, check:ci, check:panels 는 §2.1(1) 대상이 아니다. 계획서대로 typecheck, 이 PR 의 check, 깨뜨린 실행을 적었다.

Changelog

Docs

• The MQTT contract has its first vectors. docs/mqtt-vectors/ holds nine, for the topic table and the two roles in docs/mqtt-spec.md: the sleep words and sleep/state, param/N and its empty payload, knob/N as a difference, pattern by name or slug, and what a Publisher ignores and sends. npm run check:mqtt-vectors in web/ replays them against a fresh virtual panel each, through a test broker of its own (web/scripts/drift/_broker.ts), and the drift workflow runs it on every pull request.

for another k

• k12: a send takes "retain": true, so a retained snapshot can sit on the broker before the panel subscribes, and the broker hands it over on SUBSCRIBE with the retain flag set. Each out entry carries retain. open() leaves the panel on Broadcast with the role off, so a channel vector starts with POST /api/mqtt?channel=ch1 (or live, 5) and a wait.
• k12: rest-vectors.ts (k6's, now on dev) passes no sender, so a docs/rest-api-vectors/mqtt-*.json with an mqtt step throws this suite brings no sender for mqtt, and one without it reads /api/mqtt with no broker set (state no broker configured). For /api/mqtt on a connected panel, rest-vectors.ts needs import { mqtt } from "./_broker" and replay("docs/rest-api-vectors", { mqtt }). A vector opens a channel only for the kinds its steps use, so the other REST vectors pay nothing. That file is in k6's row, not k12's.
• k21: AGENTS.md can list npm run check:mqtt-vectors and docs/mqtt-vectors/ beside docs/mqtt-spec.md.
• k22: docs/README.md names docs/mqtt-vectors/, and web/ARCHITECTURE.md or web/README.md can say _broker.ts is a test broker, not a client.
• k9's file, for the maintainer: tools/virtual-panel/transports/mqtt.ts does not call setNoDelay(true) on its socket. Against a broker that delays its ACK, the panel's second publish in a row waits about 40 ms. _broker.ts works around it (가정, fifth item).

for an issue

• docs/mqtt-vectors/topics-param.json (step 09, an empty param/3 20 ms after step 07 wrote 0). docs/mqtt-spec.md line 23, "empty payload releases the hold", and line 38, "An empty payload releases it explicitly." In the firmware flushCoalescedRemote() (features/mqtt/core_mqtt.h line 648) calls PatternflowBus::releaseAbsolute(), which keeps a channel written less than ABSOLUTE_RELEASE_GRACE_MS (250 ms) ago (src/core_bus.h lines 106 to 111). releaseAbsoluteNow() beside it has no grace.
• docs/mqtt-vectors/topics-knob.json (step 11, a count 27 past the last). docs/mqtt-spec.md line 39, "The panel diffs it against the last value it received and injects the difference as a detent delta." applyRemoteKnob() cuts the pending delta to ±16 (KNOB_PENDING_FLUSH, features/mqtt/core_mqtt.h lines 120 and 599 to 603).

Upstream

• What: Add docs/mqtt-vectors/ (nine vectors for the topic table and the two roles in docs/mqtt-spec.md, and a README), web/scripts/drift/_broker.ts (a test MQTT 3.1.1 broker and the suite's sender) and web/scripts/drift/mqtt-vectors.ts (check:mqtt-vectors).
• Checks: npm run typecheck, npm run lint and npm run check:drift (mqtt-vectors among them) pass; firmware/ and web/src/ are untouched.
• Docs map: four new rows from docs/mqtt-vectors/README.md, all resolving.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bqrhsc29GLhQvHPem3UshZ

---

Generated by Claude Code