[DONE] 정리 4단계 PR 12 — MQTT 벡터가 채널과 스냅숏을, REST 벡터가 /api/mqtt 를 가상 패널에 돌려 본다

[patternflow-bot]

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

정리 4단계 계획서 표의 PR 12 다. MQTT 계약의 채널과 스냅숏을 벡터 여섯 개로, /api/mqtt 를 REST 벡터 일곱 개로 적었고, 이미 있는 check:mqtt-vectors 와 check:rest-vectors 가 그대로 가상 패널에 돌려 본다. 머지되면 채널 1~4 의 구독자 고정, Broadcast 에 스냅숏이 없는 것, 스냅숏이 쓴 값을 덮는 것, 비밀번호를 돌려주지 않는 것이 스펙이나 가상 패널과 어긋날 때 PR 마다 drift 검사가 빨개진다.

좋아지는 것: 없음

할 일

• 계획서 PR 12 행(k12)과 D7~D12, 앞 PR 9([DONE] 정리 4단계 PR 9 — 가상 패널이 MQTT 브로커에 붙는다: 역할, 채널, 토픽, 8초 스냅숏 #74), 10([DONE] 정리 4단계 PR 10 — 가상 패널이 /api/mqtt 로 브로커와 역할을 받고, status 에 MQTT 세 칸을 보인다 #77), 11([DONE] 정리 4단계 PR 11 — MQTT 벡터가 시험 브로커를 거쳐 토픽과 역할을 가상 패널에 돌려 보고 check:mqtt-vectors 가 생긴다 #79), 7([DONE] 정리 4단계 PR 7 — REST 벡터가 display, knobs, crash, 파비콘, 패턴 경로와 기본 빌드에 없는 경로를 가상 패널에 돌려 본다 #81)이 k12 에 남긴 말을 읽는다
• docs/mqtt-vectors/channels-*.json 여섯
• docs/rest-api-vectors/mqtt-*.json 일곱
• 300줄 안: +217
• MQTT 스위트 열 번 연달아, 4코어에 여덟 개씩 나란히 세 번(24번), dev merge 뒤 두 스위트 다섯 번씩. 다 통과
• 일부러 깨뜨린 실행 일곱(패널 여섯, 스펙 하나), 되돌림. 첫 판 channels-forced.json 이 하나를 놓쳐 고쳤다
• typecheck, lint, check:drift, markers, 링크, 잠금, 글투, doc-map
• dev merge 한 번: PR 7([DONE] 정리 4단계 PR 7 — REST 벡터가 display, knobs, crash, 파비콘, 패턴 경로와 기본 빌드에 없는 경로를 가상 패널에 돌려 본다 #81, 070afe5)이 들어왔다. 충돌 없음, 다시 다 통과
• 이 PR 의 CI: 8c72eb5 에서 Drift checks(116503126802)와 Docs point at files that exist(38758476175) 둘 다 success
• [DONE] 직전 dev 를 다시 받아 본다: 070afe5 그대로라 merge 할 것이 없다

한 일

MQTT 벡터 여섯, 저마다 mqtt-spec.md 한 문장이다. 채널은 스펙 11행대로 POST /api/mqtt 의 prefix 로 고른다. 펌웨어가 받는 channel 인자는 스펙에 없다.

• channels-prefix.json, 14행 「Prefix patternflow is Broadcast; …」. ch3 에 붙으면 patternflow/param/1 은 무시하고 patternflow3/param/1 은 따른다. prefix 일곱(patternflow, patternflow1, 2, 4, 5, patternflow6, studio)마다 /api/mqtt 의 channel 이 broadcast, ch1, ch2, ch4, live, custom, custom 이다.
• channels-forced.json, 14행 「Channels 1–4 force the Subscriber role.」 Live 에선 발행자로 붙는다. 채널 1~4 로 옮기면 구독자고, 옮긴 다음 role=publisher 를 따로 보내도 구독자다. ch4 에서 pattern 을 따른다.
• channels-snapshot.json, 45행. 채널 15 의 스냅숏을 retain 으로 브로커에 두고 차례로 옮기면, 옮길 때마다 그 채널의 param 넷이 잡힌 값이 된다(110140, 210240, … 510540).
• channels-heartbeat.json, 45행 둘째 문장. Live 발행자는 붙자마자 retain 스냅숏을 내고, 7.9초 동안 아무것도 보내지 않다가 다음 0.2초 안에 또 낸다. 구독자로 다시 붙으면 브로커에 남은 제 스냅숏을 받아 넷 다 잡힌다.
• channels-overwrite.json, 45행 셋째 문장. ch2 와 Live 에서 param/N 900 이 먹고, 뒤에 온 스냅숏이 그 값을 덮는다.
• channels-broadcast.json, 47행. Broadcast 구독자는 retain 스냅숏을 받지 않고, param/2 800 은 스냅숏이 와도 남는다.

REST 벡터 일곱, /api/mqtt 다. rest-vectors.ts 는 MQTT sender 를 넘기지 않아 브로커가 없고, 패널은 붙지 않은 채로 답한다(PR 11 이 넘긴 말).

• mqtt-fields.json, 367행 「Also reported: …」. 예시의 키와 normal* 다섯, directorHost 를 타입으로 본다.
• mqtt-password.json, 367행 「Passwords are never returned — only whether one is set.」 처음엔 hasPassword 가 false. 폼으로 host, user, password 를 보내면 답과 다음 GET 에서 hasPassword, normalHasPassword 가 true 이고 password 도 pass 도 없다.
• mqtt-forces-sub.json, 362행 forcesSub. Live 발행자를 ch3 으로 옮기면 구독자에 forcesSub true, role=publisher 를 보내도 그대로다.
• mqtt-knobs.json, 363행. 손으로 돌린 클릭이 쌓이고(K1 3+2), 음수가 되고(K2 −4), 역할 off, 발행자, 구독자 어디서나 바로 보인다.
• mqtt-role.json, 111행, status 의 mqttRole. POST /api/mqtt?role= 세 번의 답과 status 가 같다.
• mqtt-same-fields.json, 323행. 손과 POST /api/params 다음 /api/mqtt 와 /api/status 의 knobs, params, paramActive 가 같다.
• mqtt-caps.json, 613행. MQTT 빌드의 caps 는 ["patterns","params","sleep","mqtt"] 이고 /api/mqtt 는 JSON 200 이다. 기본 빌드 쪽은 PR 7 의 absent-* 가 본다.

증거

로컬, web/, dev merge(78381ec)와 mqtt-caps.json 뒤:

$ git diff --stat origin/dev...HEAD
 docs/mqtt-vectors/channels-broadcast.json   | 14 ++++++++++++++
 docs/mqtt-vectors/channels-forced.json      | 20 ++++++++++++++++++++
 docs/mqtt-vectors/channels-heartbeat.json   | 16 ++++++++++++++++
 docs/mqtt-vectors/channels-overwrite.json   | 19 +++++++++++++++++++
 docs/mqtt-vectors/channels-prefix.json      | 20 ++++++++++++++++++++
 docs/mqtt-vectors/channels-snapshot.json    | 22 ++++++++++++++++++++++
 docs/rest-api-vectors/mqtt-caps.json        | 10 ++++++++++
 docs/rest-api-vectors/mqtt-fields.json      | 27 +++++++++++++++++++++++++++
 docs/rest-api-vectors/mqtt-forces-sub.json  | 11 +++++++++++
 docs/rest-api-vectors/mqtt-knobs.json       | 17 +++++++++++++++++
 docs/rest-api-vectors/mqtt-password.json    | 17 +++++++++++++++++
 docs/rest-api-vectors/mqtt-role.json        | 11 +++++++++++
 docs/rest-api-vectors/mqtt-same-fields.json | 18 ++++++++++++++++++
 13 files changed, 217 insertions(+)

$ npm run check:mqtt-vectors
docs/mqtt-vectors/channels-broadcast.json: same
docs/mqtt-vectors/channels-forced.json: same
docs/mqtt-vectors/channels-heartbeat.json: same
docs/mqtt-vectors/channels-overwrite.json: same
docs/mqtt-vectors/channels-prefix.json: same
docs/mqtt-vectors/channels-snapshot.json: same
docs/mqtt-vectors/topics-*.json: same          (PR 11 의 아홉, 그대로)
passed   mqtt-vectors
# 한 번에 2 s 안. 열 번 연달아 exit 0. 4코어에 여덟 개씩 나란히 세 번, 24번 다 exit 0.

$ npm run check:rest-vectors
docs/rest-api-vectors/mqtt-caps.json: same
docs/rest-api-vectors/mqtt-fields.json: same
docs/rest-api-vectors/mqtt-forces-sub.json: same
docs/rest-api-vectors/mqtt-knobs.json: same
docs/rest-api-vectors/mqtt-password.json: same
docs/rest-api-vectors/mqtt-role.json: same
docs/rest-api-vectors/mqtt-same-fields.json: same
docs/rest-api-vectors/{absent,device,patterns,state}-*.json: same   (PR 6, PR 7 의 서른넷, 그대로)
passed   rest-vectors

# channels-heartbeat.json 의 out, 패널 쪽
step 02 out mqtt {"topic":"patternflow5/snapshot","payload":"<string>","retain":true} by 20 ms
step 03 out mqtt <absent> by 7900 ms
step 04 out mqtt {"topic":"patternflow5/snapshot","payload":"<string>","retain":true} by 200 ms
step 06 status.paramActive[0..3] true

# 깨뜨린 일곱. 각각 git checkout 으로 되돌렸고, 되돌린 뒤 passed
# 1) mqtt.ts: Broadcast 도 스냅숏을 구독한다 (showPrefix 를 /^patternflow[1-5]?$/ 로)
docs/mqtt-vectors/channels-broadcast.json: drift
  only in the vector: step 03 status.paramActive[0] false, … step 07 status.params[1] 800
  only in the panel: step 03 status.paramActive[0] true, … step 07 status.params[1] 200
failed   mqtt-vectors
# 2) mqtt.ts: HEARTBEAT_MS 8000 을 10000 으로
docs/mqtt-vectors/channels-heartbeat.json: drift
  only in the vector: step 04 out mqtt {"topic":"patternflow5/snapshot","payload":"<string>","retain":true} by 200 ms
  only in the panel: step 04 out mqtt nothing by 200 ms
failed   mqtt-vectors
# 3) mqtt.ts: ch4 가 구독자로 묶지 않는다 (forcesSub 를 /^ch[1-3]$/ 로)
#    첫 판 channels-forced.json 은 이걸 통과시켰다. 고친 판:
docs/mqtt-vectors/channels-forced.json: drift
  only in the vector: step 10 status.mqttRole "subscriber", step 11 status.mqttRole "subscriber", step 13 status.active "Wave Saw"
  only in the panel: step 10 status.mqttRole "publisher", step 11 status.mqttRole "publisher", step 13 status.active "Origin"
failed   mqtt-vectors
# 4) mqtt.ts: ch1 이 묶지 않는다 (/^ch[2-4]$/)
docs/mqtt-vectors/channels-forced.json: drift
  only in the vector: step 03 status.mqttRole "subscriber", step 04 status.mqttRole "subscriber"
  only in the panel: step 03 status.mqttRole "publisher", step 04 status.mqttRole "publisher"
failed   mqtt-vectors
# 5) mqtt.ts: ch3 이 묶지 않는다 (/^ch[124]$/), REST 스위트
docs/rest-api-vectors/mqtt-forces-sub.json: drift
  only in the vector: step 02 reply.body.forcesSub true, step 02 reply.body.role "subscriber", … step 04 reply.body.role "subscriber"
  only in the panel: step 02 reply.body.forcesSub false, step 02 reply.body.role "publisher", … step 04 reply.body.role "publisher"
failed   rest-vectors
# 6) mqtt-http.ts: GET /api/mqtt 의 답에 password 를 싣는다
docs/rest-api-vectors/mqtt-password.json: drift
  only in the vector: step 02 reply.body.password <absent>, step 03 reply.body.password <absent>
  only in the panel: step 02 reply.body.password "hunter2", step 03 reply.body.password "hunter2"
failed   rest-vectors
# 7) mqtt-spec.md 45행 "every 8 seconds" 를 "every 10 seconds" 로
docs/mqtt-vectors/channels-heartbeat.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

$ npm run typecheck                    # exit 0
$ npm run lint -- --max-warnings=0     # exit 0
$ npm run check:drift
passed bom, bom-schematic, changelog, editions, features, links-absolute, markers, mqtt-vectors, osc-vectors, presets, rest-vectors, shared, virtual-panel
skipped roadmap                        # 원래 레포를 못 읽는다. CI 는 PF_DRIFT_STRICT=1 로 돈다
$ npx tsx scripts/drift.ts markers     # passed
$ python3 ../.github/scripts/check_links.py
all 725 relative links resolve
$ npm run check:human-lock
check:human-lock: no locked words changed
$ npm run check:voice                  # JSON 은 읽지 않는다. 이 본문은 - 로 읽혔다
check:voice: nothing found
$ git fetch --tags && npm run doc-map  # CSV 는 git checkout 으로 되돌렸다
1111 links from 222 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 이 바꾸지 않는다. 벡터는 JSON 이라 링크를 더하지 않는다.

가상 패널의 POST 순서를 본 실행. 버릴 스크립트로 start({ features: ["mqtt"], clock: "manual" }) 한 패널에 차례로 보냈다(커밋하지 않음):

prefix=patternflow3&role=subscriber  {"role":"subscriber","channel":"ch3","prefix":"patternflow3"}
prefix=patternflow5&role=publisher   {"role":"subscriber","channel":"live","prefix":"patternflow5"}
role=publisher                       {"role":"publisher","channel":"live","prefix":"patternflow5"}

GitHub, 이 PR: head 8c72eb5 에서 「Drift checks / check」(job 116503126802, PF_DRIFT_STRICT=1) 로그에 passed mqtt-vectors, passed rest-vectors, passed roadmap, check:human-lock: no locked words changed. 「Docs point at files that exist / check」(run 38758476175)도 success. web/** 가 바뀌지 않아 「Web CI」는 돌지 않았고, typecheck 와 lint 는 위의 로컬 결과다. [DONE] 직전 dev 는 070afe5 그대로라 더 merge 할 것이 없다.

실행법

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

가정

• 기준 브랜치는 dev(머리말). 표가 PR 12 에 적은 두 자리(docs/mqtt-vectors/channels-*.json, docs/rest-api-vectors/mqtt-*.json)에만 더했다. README 둘은 k6, k11 행이고 이미 channels- 와 mqtt- 를 말해서 고치지 않았다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV, rest-vectors.ts, tools/virtual-panel/ 도 안 고쳤다. 라벨은 앞 PR 들처럼 달지 않았다.
• 채널은 prefix 로 고른다. 스펙 11행이 POST /api/mqtt 가 받는 것으로 host, port, user, password, prefix, role 을 꼽고, 14행이 「The prefix is the channel」이라 한다. 펌웨어의 channel 인자는 스펙에 없어 쓰지 않았다(D8). 펌웨어는 이 POST 에서 prefix 를 받지 않는다. 아래 for an issue.
• prefix 와 role 을 한 요청에 보내면 가상 패널은 role 을 지금 채널에 먼저 적용하고 그다음 prefix 로 옮긴다(위 실행). 스펙은 둘의 순서를 말하지 않는다. 그래서 역할이 걸리는 곳(channels-forced.json, mqtt-forces-sub.json)은 prefix 와 role 을 따로 보낸다. 깨뜨린 3 을 첫 판이 통과시킨 까닭이 이것이었다.
• 하트비트 창은 7.9초 조용함과 그다음 0.2초다. 스펙은 「every 8 seconds」에 허용 폭을 말하지 않는다. 가상 패널의 프레임은 16.7 ms 라 스냅숏은 붙은 지 8.013초에 나간다.
• 스냅숏의 페이로드는 "<string>" 로만 본다. 스펙은 「compact JSON of the mid-join state, including param:[a,b,c,d]」 라 param 말고 어떤 키가 있는지 정하지 않는다. 벡터가 보내는 스냅숏도 param 만 싣는다. 구독자가 pattern 이나 message 로 무엇을 하는지는 스펙에 없다(D8).
• channels-heartbeat.json 의 다시 붙는 쪽은 패널이 발행자일 때 남긴 제 스냅숏을 구독자로 받는다. 값이 기본 500 이라 params 는 그대로고, paramActive 가 넷 다 true 가 되는 것으로 스냅숏이 왔음을 본다. 그 사이 브로커에 스냅숏을 보낸 것은 패널뿐이다.
• message 의 retain 칸(broadcast: yes · channels: no)은 벡터가 없다. 보내는 쪽이 정할 플래그이고, 패널은 message 를 받기만 한다. 패널 쪽에서 돌려 볼 것이 없다. /api/mqtt 의 channel 이 off 가 되는 때도 스펙이 말하지 않아 보지 않았다.
• mqtt-same-fields.json 이 인용한 323행의 뒷부분(MQTT 없는 빌드는 그 경로가 없다)은 PR 7 의 absent-routes.json 이 본다. features 가 벡터마다 하나라 한 벡터에 둘을 담을 수 없다.
• mqtt-caps.json 은 caps 의 순서까지 본다. 110행이 기본 셋을 먼저 적고 「each edition adds its own」이라 하고, 펌웨어도 코어 셋 뒤에 feature 의 cap 을 붙인다(core_status_http.h 251~264행).
• REST 벡터는 rest-vectors.ts 에 MQTT sender 가 없어 브로커 없이 돈다. host 를 주는 것은 mqtt-password.json 하나이고 역할이 off 라 아무 데도 걸지 않는다.
• 스크린샷은 없다. 화면이 없는 PR 이다.
• firmware/ 와 web/src/ 를 건드리지 않아 build.sh all, check:ci, check:panels 는 §2.1(1) 대상이 아니다. 계획서대로 typecheck 와 이 PR 의 검사, 깨뜨린 실행을 적었다.

Changelog

Docs

• The MQTT vectors reach the channels and the snapshot, and /api/mqtt has REST vectors. Six more in docs/mqtt-vectors/ replay the prefix naming the channel, channels 1–4 forcing Subscriber, the retained snapshot on channels 1–4 and Live, the Publisher's eight-second heartbeat, a snapshot overwriting a param/N write, and Broadcast taking no snapshot. Seven in docs/rest-api-vectors/ read GET and POST /api/mqtt: its fields, the password it never returns, forcesSub, the knob counts in every role, mqttRole in status and the mqtt cap.

for an issue

• POST /api/mqtt and the broker. docs/mqtt-spec.md line 11: "Set on the panel's MQTT console page or with POST /api/mqtt (host, port, user, password, prefix, role)." The firmware's postOnLoop() (features/mqtt/core_mqtt_http.h lines 148 to 214) reads only channel and role, answers a request with neither 400 {"ok":false,"error":"channel or role required"} (line 162), and ignores host, port, user, password and prefix. The broker is saved by POST /api/mqtt/config (configOnLoop(), line 216), which takes the password as pass (line 241). Vectors that set the prefix or the password there: every channels-*.json, mqtt-password.json (step 02), mqtt-forces-sub.json (steps 01 and 02). web/scripts/drift/_broker.ts (PR 11) points every MQTT vector at its broker the same way.
• Nothing else. Each vector was set against core_mqtt.h: snapshot only on patternflow1 to patternflow5 (isChannelShowPrefix(), line 296, used at 949 and 964), the heartbeat (SNAPSHOT_HEARTBEAT_MS, line 107, from handle(), line 1431), a Publisher ignoring a non-empty snapshot (line 728), channels 1 to 4 forcing Subscriber (lines 1100, 1131, 1305, 1333), knobs from the hand in every role until knob/N arrives (lastKnobsCopy(), line 1374, and update(), line 1456), and no password in sendStatus() (core_mqtt_http.h lines 73 to 133).

for another k

• k10's file, for the maintainer: tools/virtual-panel/transports/mqtt-http.ts applies role on the channel the panel is on and saves prefix after it. On ch3, POST /api/mqtt?prefix=patternflow5&role=publisher leaves a Subscriber on Live, and a second role=publisher is needed (run above). The spec does not order the two, and a client reading it would expect a Publisher on Live. The vectors here send the two apart, so changing the order breaks none of them.
• k11's README, for the maintainer: its paragraph on what has no vectors could add the message retain column, for the reason in 가정. The plan gives that file to no later k.
• k23: nothing from this PR.

Upstream

• What: Add six MQTT vectors to docs/mqtt-vectors/ (channels-: the prefix as the channel, channels 1–4 forcing Subscriber, the retained snapshot, the Publisher's heartbeat, a snapshot overwriting a write, Broadcast with no snapshot) and seven REST vectors for GET and POST /api/mqtt to docs/rest-api-vectors/ (mqtt-).
• Checks: npm run typecheck, npm run lint, npm run check:mqtt-vectors and npm run check:rest-vectors pass; firmware/ and web/src/ are untouched.
• Docs map: none. The vectors are JSON and add no links.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EPRDTPDwckZBFHTbCWekXj