[DONE] 정리 4단계 PR 7 — REST 벡터가 display, knobs, crash, 파비콘, 패턴 경로와 기본 빌드에 없는 경로를 가상 패널에 돌려 본다

[patternflow-bot]

lsh / https://claude.ai/code/session_01USkJSdcmzkr3PaK1sjciFx

정리 4단계 계획서 표의 PR 7 이다. REST 벡터 스물다섯 개를 docs/rest-api-vectors/ 에 더했다. 기기 상태의 나머지(display, knobs, crash, 파비콘), 모든 경로가 같이 지키는 헤더와 404, 패턴 경로, 그리고 기본 빌드에 없어야 할 feature 경로다. 머지되면 check:rest-vectors 가 34개를 PR 마다 돌려서, 가상 패널이 이 문장들과 어긋나거나 기본 빌드에 feature 가 새어 들면 빨개진다.

좋아지는 것: 없음

할 일

• 계획서 k7 행과 D7, D8, D9, D11, D12, docs/contract-vectors.md, _vectors.ts, rest-state.ts, rest-patterns.ts, PR 4·5·6 본문의 「for another k」를 읽는다
• device-*.json 열둘, patterns-*.json 열, absent-*.json 셋
• 300줄 안: +297
• 일부러 깨뜨린 실행 셋(스펙 문장, 기본 빌드에 새어 든 cap 과 경로, 빈 featureNav), 되돌림
• typecheck, lint, check:rest-vectors, check:drift, markers, 링크, 잠금, 글투, doc-map
• dev merge 한 번: PR 11([DONE] 정리 4단계 PR 11 — MQTT 벡터가 시험 브로커를 거쳐 토픽과 역할을 가상 패널에 돌려 보고 check:mqtt-vectors 가 생긴다 #79), PR 14([DONE] 정리 4단계 PR 14 — OSC 벡터 열한 개가 가상 패널에서 돌고, check:osc-vectors 가 PR 마다 본다 #80) 이 들어왔다(충돌 없음, 다 MQTT·OSC 파일). 벡터 34, typecheck, lint, check:drift 다시 통과
• 이 PR 의 CI, 마지막 head ad64b8e: 「Drift checks / check」(116498096709, PF_DRIFT_STRICT=1)와 「Docs point at files that exist / check」(116498096322) 둘 다 success. GitHub 이 본 merge 상태는 clean
• [DONE] 직전 dev 를 다시 받아 본다: 마지막 merge ad64b8e 뒤로 dev(0c8cedb)는 그대로다

한 일

벡터 스물다섯. 모두 기본 빌드("features": [])다.

device-, 열둘:

• device-cors.json, #transport 「Only /api/patterns/select and /api/display send Access-Control-Allow-Origin: *.」 그 둘엔 * 가 있고, status, patterns, knobs, params, 사이드카, 없는 경로의 404 엔 그 헤더가 없다.
• device-no-store.json, 「Every JSON endpoint sends Cache-Control: no-store, and so does the plain-text 404.」 JSON 경로 열하나(JSON 404 인 crash 와 select 포함)와, 없는 경로의 text/plain 404.
• device-compressed.json, 「Nothing under /api/ is compressed.」 Accept-Encoding: gzip, deflate 를 보내도 status, patterns, .pfm 에 Content-Encoding 이 없다.
• device-favicon.json, 파비콘 줄. patternflow.local 에 204 와 immutable, patternflow.fritz.box 에 204 와 no-store.
• device-host.json, Host gating 줄. IPv4, 점 없는 이름, .local 이름이 포트가 있든 없든 immutable, patternflow.fritz.box 와 patternflow.work:80 은 no-store.
• device-crash.json, #delete-apicrash. status 에 crash 가 없을 때 DELETE /api/crash 는 404 와 스펙의 본문 그대로다.
• device-removed.json, #knobs-and-parameters 「/api/knob and /remote existed and were removed as unused …」 /api/knob(GET, POST), /remote, /api/frame 이 404.
• device-knobs-get.json. K1 +2, K3 −1 뒤 clicks 가 [2,0,-1,0] 이고 status 의 knobs 와 같다. inv, sub, raw 는 네 칸을 타입으로 본다.
• device-knobs-post.json. 폼 본문 inv=0&sub=4, 그다음 inv1=1&sub2=2 의 답이 GET 꼴이고 clicks 는 그대로다(「without moving the knob」). 한 프레임 뒤에도 그대로고, 그 뒤 K2 한 칸은 −1, K3 한 칸은 +2 로 센다.
• device-display-state.json. sat=2&gamma_g=2.5 의 답에 표의 키 열둘과 읽기 전용 여섯이 다 있고, 다음 brightness=128 의 답에도 앞의 두 값이 남아 있다.
• device-display-brightness.json, status 표 88행. /api/display?brightness=77, 255 가 답과 status 의 brightness 를 같이 바꾼다.
• device-display-read-only.json. ?sleep=1 의 답에 sleep 이 있지만 패널은 잠들지 않는다.

patterns-, 열:

• patterns-list.json, 「active is an index into patterns, or -1 while nothing is loaded.」 키를 타입으로, presets 1, mounted true. index 2 를 고르고 한 프레임 뒤 active 가 2.
• patterns-select.json, 「Queued and applied in loop(), …」 index 1 의 답은 {ok:true,index:1,name:<string>}, 고른 패턴이다. 다음 프레임 전의 /api/patterns 는 아직 0, 한 프레임 뒤 1 이고 activeIsModule 이 true.
• patterns-select-404.json. index −1, 9999, 모르는 이름이 404 이고 Origin 그대로다.
• patterns-select-name.json, 「Display name, exact match.」 origin 은 404, Origin 은 index 0.
• patterns-select-step.json. 0 에서 +1 은 1, −1 은 0, 또 −1 은 끝, 거기서 +1 은 다시 0 이다(감아 돈다). + 는 %2B 로 보낸다.
• patterns-file-sidecar.json. wave_saw 의 사이드카가 JSON 으로 오고 name, abi, 네 칸 knobs, slug 가 있다.
• patterns-file-preset.json, 「Presets have no sidecar.」 origin 의 json 은 404.
• patterns-file-404.json. 없는 slug 의 pfm, json, thumb 이 404.
• patterns-file-download.json. pfm(기본)과 json 에 Content-Disposition 이 있다.
• patterns-thumb.json. Origin 의 썸네일은 처음엔 404, 3 초 돌리고 떠난 뒤 200.

absent-, 셋:

• absent-caps.json, 110행. 기본 빌드의 caps 가 ["patterns","params","sleep"] 그대로다.
• absent-feature-nav.json, 112행. featureNav 가 [].
• absent-routes.json, #conventions-for-future-additions 613행. /api/mqtt, /api/midi, /api/audio(GET, POST 하나씩), /api/audio-in, /api/clock, /api/shows 가 plain-text 404 다. 경로가 있는 JSON 404 가 아니다.

증거

로컬, web/, dev merge(ad64b8e) 뒤:

$ git diff --stat origin/dev...HEAD
 25 files changed, 297 insertions(+)

$ time npm run check:rest-vectors
── rest-vectors
docs/rest-api-vectors/absent-caps.json: same               (6 줄: contract, says, status, caps)
docs/rest-api-vectors/absent-feature-nav.json: same        (3)
docs/rest-api-vectors/absent-routes.json: same             (20)
docs/rest-api-vectors/device-compressed.json: same         (8)
docs/rest-api-vectors/device-cors.json: same               (12)
docs/rest-api-vectors/device-crash.json: same              (6)
docs/rest-api-vectors/device-display-brightness.json: same (6)
docs/rest-api-vectors/device-display-read-only.json: same  (5)
docs/rest-api-vectors/device-display-state.json: same      (24)
docs/rest-api-vectors/device-favicon.json: same            (6)
docs/rest-api-vectors/device-host.json: same               (10)
docs/rest-api-vectors/device-knobs-get.json: same          (23)
docs/rest-api-vectors/device-knobs-post.json: same         (40)
docs/rest-api-vectors/device-no-store.json: same           (18)
docs/rest-api-vectors/device-removed.json: same            (6)
docs/rest-api-vectors/patterns-file-404.json: same         (5)
docs/rest-api-vectors/patterns-file-download.json: same    (6)
docs/rest-api-vectors/patterns-file-preset.json: same      (3)
docs/rest-api-vectors/patterns-file-sidecar.json: same     (10)
docs/rest-api-vectors/patterns-list.json: same             (11)
docs/rest-api-vectors/patterns-select-404.json: same       (6)
docs/rest-api-vectors/patterns-select-name.json: same      (9)
docs/rest-api-vectors/patterns-select-step.json: same      (10)
docs/rest-api-vectors/patterns-select.json: same           (11)
docs/rest-api-vectors/patterns-thumb.json: same            (5)
docs/rest-api-vectors/state-*.json: same                   (k6 의 아홉, 그대로)
passed   rest-vectors
real 0m2.271s

# 깨뜨린 셋. 각각 git checkout 으로 되돌렸고, 되돌린 뒤 passed
# 1) rest-api.md 20행 "send `Access-Control-Allow-Origin: *`" 의 send 를 return 으로
docs/rest-api-vectors/device-cors.json: drift
  only in the vector: says docs/rest-api.md
  only in the panel: says not in docs/rest-api.md
exit 1
# 2) 코어 transport(rest-patterns.ts)가 caps 에 "audio" 를 내고 GET /api/audio 를 받는다
docs/rest-api-vectors/absent-caps.json: drift
  only in the vector: step 01 reply.body.caps ["patterns","params","sleep"]
  only in the panel: step 01 reply.body.caps ["patterns","params","sleep","audio"]
docs/rest-api-vectors/absent-routes.json: drift
  only in the vector: step 05 reply.headers.content-type "text/plain", step 05 reply.status 404
  only in the panel: step 05 reply.headers.content-type "application/json", step 05 reply.status 200
# 3) rest-state.ts 의 featureNav 를 [["/x","X","y"]] 로
docs/rest-api-vectors/absent-feature-nav.json: drift
  only in the vector: step 01 reply.body.featureNav []
  only in the panel: step 01 reply.body.featureNav [["/x","X","y"]]

$ 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 으로 되돌렸다
1104 links from 220 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 은 k6 뒤와 같다. 벡터는 JSON 이라 링크를 더하지 않는다.

GitHub, 이 PR: head ad64b8e 에서 「Drift checks / check」(116498096709) 로그에 passed rest-vectors, passed roadmap, check:human-lock: no locked words changed. 「Docs point at files that exist / check」(116498096322)도 success. web/** 가 바뀌지 않아 「Web CI」는 돌지 않았고, typecheck 와 lint 는 위의 로컬 결과다.

깨뜨린 2 는 처음에 mqtt-http.ts 의 feature 를 null 로 바꿔 해 봤다. 그 transport 는 MQTT 클라이언트(mqtt.ts)가 같이 붙어야 돌아서 /api/status 가 500 으로 죽었고, 벡터 대부분이 그 500 으로 빨개졌다. 무엇을 잡는지 보이지 않아서 위의 꼴로 다시 했다.

벡터를 쓰기 전에 가상 패널을 띄워 curl 로 헤더를 봤다. 파일 경로와 썸네일은 Transfer-Encoding: chunked 라 Content-Length 가 없어, 썸네일의 16,392 바이트는 벡터가 볼 수 없다.

실행법

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

가정

• 기준 브랜치는 dev(머리말). 표가 k7 에 적은 device-*, patterns-*, absent-* 만 더했다. README, CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV, tools/virtual-panel/ 는 안 고쳤다. 라벨은 앞 PR 들처럼 달지 않았다.
• 모듈이 있어야 하는 벡터는 wave_saw 를 쓴다. rest-api.md 의 GET /api/patterns 예시가 이름을 댄 모듈이고 Basics 에 있다. 목록 길이(34)는 어디에도 박지 않았다. 범위 밖 index 는 −1 과 9999, 끝으로 감긴 index 는 <integer> 다. 그래서 patterns 배열의 원소(Origin 의 module: null)는 보지 못한다. 모양 언어의 배열은 길이가 맞아야 한다.
• 지금 패턴을 읽는 벡터는 먼저 index 0 을 고르고 한 프레임 기다린다. 새 가상 패널은 늘 Origin 에서 시작하지만, 기기는 기억한 패턴으로 시작한다. 질문 29 의 --panel 이 생기면 그대로 쓸 수 있게 했다.
• select 의 답은 고른 패턴이다(D8, 질문 27). 이전 상태라고 하는 38행은 k23 몫이다(PR 5 가 적었다).
• 스펙이 값이나 꼴을 정하지 않은 곳은 있는지만 본다. 읽기 전용 여섯은 <any>, Content-Disposition 은 <string> 이다. 스펙은 attachment 라고만 하고 펌웨어와 가상 패널은 attachment; filename="<slug>.<ext>" 를 보내는데, 모양 언어엔 앞부분 맞추기가 없다. inv, sub, raw 의 기본값도 타입으로만 본다. 「most encoders are 4」는 부품을 말하는 것이라, POST 벡터가 inv=0&sub=4 로 먼저 정하고 시작한다.
• sub2=2 뒤 K3 한 칸이 클릭 둘인 것은 가상 패널의 부품이 한 칸에 edge 넷이라서다(EDGES_PER_DETENT). 스펙의 「how many edges make one click」 그대로다.
• 범위 밖의 brightness, screen, level, sub=3 에 무엇을 하는지는 스펙이 말하지 않아 벡터가 없다(D8). 409(볼륨이 없을 때), 재부팅에 돌아가는 색 보정, NVS 저장, Host 가 없는 요청도 없다. 가상 패널엔 볼륨을 뺄 길도 재부팅도 없고, _vectors.ts 는 Host 를 늘 보낸다.
• 썸네일은 3 초 돌린 뒤 떠난다. 스펙은 「a couple of seconds」, 펌웨어는 2000 ms(THUMB_MIN_RUN_MS)다.
• display 의 sleep 이 status 의 sleep 을 「mirror」한다는 것은 값으로 보지 않았다. status 는 boolean 이고 펌웨어의 /api/display 는 0/1 을 찍는다(core_display_http.h:146). 아래 k23.
• /api/audio-in, /api/clock, /api/shows 는 계획서 k7 이 이름을 댄 셋 밖이지만, 기본 빌드에 없어야 할 feature 경로라 같은 벡터에 넣었다. /api/weather 는 rest-api.md 에 없어 뺐다.
• 300줄 안에 두려고 큰 step 몇 개를 두세 줄로 접었다.
• 스크린샷은 없다. 화면이 없는 PR 이다.
• firmware/ 와 web/src/ 를 건드리지 않아 build.sh all, check:ci, check:panels 는 §2.1(1) 대상이 아니다. 계획서대로 typecheck 와 이 PR 의 검사, 깨뜨린 실행을 적었다.

Changelog

Docs

• The REST vectors reach the rest of the core. Twenty-five more in docs/rest-api-vectors/ read /api/display, /api/knobs, DELETE /api/crash, the favicon, the pattern routes and the headers every route shares. On the default build caps is ["patterns","params","sleep"] and each feature's route answers the plain-text 404.

for an issue

D9: 이 PR 의 벡터가 담은 펌웨어와의 어긋남은 없다. 벡터마다 펌웨어와 맞대 봤다. CORS 는 core_display_http.h:163 과 core_patterns_http.h:1012,1018 에만 있고, 404 는 core_http.h:73-75 의 no-store 와 text/plain, 파비콘은 core_send.h:427 의 noContent, crash 는 core_status_http.h:588-593 이다. select 는 이름을 equals 로 맞추고 step 은 감아 돌며(core_patterns_http.h:957-990), 답은 고른 패턴이다. 기본 caps 는 core_status_http.h:241 부터 셋이고, /api/knob, /remote, /api/frame 은 등록하는 곳이 없다.

for another k

• k12, k18, k20: absent-routes.json 과 absent-caps.json 은 features: [] 에서만 돈다. feature 를 넣은 빌드의 caps 와 경로는 그 PR 들 몫이고, 여기 벡터와 부딪히지 않는다.
• k23: (1) 38행(select 는 이전 상태)과 259행 예시(고른 패턴). (2) 21행(404 는 plain text)과 610행(오류는 JSON 본문). 이 PR 은 없는 경로엔 21행을, 경로가 있는 404(crash, select)엔 610행을 따랐다. (3) 207행·222행 display 의 sleep 의 꼴. status 는 boolean, 펌웨어 display 는 0/1. (4) 110행 caps 줄이 audio-in, clock, midi 를 빠뜨린 것(발견 5).
• _vectors.ts(D10, 얼었다): 빈 배열 [] 모양은 맞으면 줄을 하나도 남기지 않는다. absent-feature-nav.json 이 그래서 (3)이고, 틀리면 위 깨뜨린 3 처럼 보인다. 앞부분 맞추기가 없어 Content-Disposition: attachment 는 <string> 으로만 본다. 고치려면 계획서에 행이 있어야 한다.

Upstream

• What: Add twenty-five REST vectors to docs/rest-api-vectors/: device-* for display, knobs, crash, the favicon and the headers every route shares, patterns-* for the list, select and module files, absent-* for what the default build leaves out.
• Checks: npm run typecheck, npm run lint 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_01USkJSdcmzkr3PaK1sjciFx

---

Generated by Claude Code