[DONE] 정리 4단계 PR 23 — REST 와 MIDI 스펙에서 두 말을 하던 줄 열 곳이 한 말을 하고, 그 줄을 옮긴 벡터 둘이 따라간다

[patternflow-bot]

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

정리 4단계 계획서 표의 PR 23 이다. rest-api.md 와 midi-spec.md 가 스스로 두 말을 하던 줄 열 곳을, 그 경로나 메시지를 정한 절이 이긴다는 질문 27 의 기본값대로 고쳤다. 머지되면 스펙을 보고 만드는 쪽이 「HTTP 로는 노브를 못 쓴다」나 「select 는 이전 상태를 준다」 같은 진 줄을 더는 만나지 않고, 고친 줄을 옮겨 둔 벡터 둘이 새 문장을 본다.

좋아지는 것: 없음

할 일

• 계획서 k23 행과 질문 27, 벡터 PR 본문([DONE] 정리 4단계 PR 1 — 가이드의 보드 시뮬레이터가 손이 아닌 입력도 받고, 상태를 /api/status 처럼 내준다 #69~[DONE] 정리 4단계 PR 18 — MIDI 로 나가는 메시지 벡터 열한 개와 /api/midi 벡터 아홉 개가 가상 패널에서 돈다 #88)의 k23 줄을 모은다
• 진 줄을 고친다: rest-api.md 일곱 곳, midi-spec.md 세 곳
• 버전 기록: rest-api.md 1.5, midi-spec.md 1.2 줄 끝에 한 문장씩
• 고친 줄을 옮긴 벡터 둘(absent-caps.json, state-params-subset.json)을 다시 옮긴다
• 깨진 실행: 스펙만 고친 상태에서 check:rest-vectors 가 바로 그 둘로 실패
• check:rest-vectors, check:midi-vectors, check:drift, typecheck, lint, 링크, 잠금, 글투, doc-map
• 300줄 안: +21 −14
• CI, 이 PR 의 head
• [DONE] 직전 dev 를 다시 받아 본다: dev(c8e877f)가 이 브랜치의 시작점 그대로라 merge 할 것이 없다

한 일

줄 번호는 dev(c8e877f) 판이다. 줄마다 진 쪽, 이긴 쪽, 고친 꼴 순서다.

rest-api.md:

• 38행 「POST /api/sleep and GET /api/patterns/select therefore return the previous state.」 이긴 쪽은 select 절의 예시(259행)와 263행이다. 이제 sleep 만 이전 상태를 주고, select 는 큐에 넣은 패턴으로 답하며 /api/patterns 와 /api/status 가 다음 프레임까지 옛 패턴을 말한다고 쓴다. patterns-select.json(PR 7)이 이미 그렇게 본다.
• 110행 caps 줄이 Audio 의 audio-in, midi 와 Performance 의 clock 을 빠뜨렸다. 이긴 쪽은 그 feature 들의 절이다: Microphone 386행, Clock 493행, midi-spec.md 68행. 펌웨어의 descriptor 와 firmware/bundles/{audio,performance}/ 의 목록도 같다.
• 165행 「at least one required」는 pN 하나가 꼭 있어야 한다고 읽힌다. 이긴 쪽은 178행 d1..d4 「for a client that has only those」다. 「A request needs at least one pN or dN.」 펌웨어도 dN 하나를 쓰기로 센다(core_status_http.h:659).
• 595행 노브 읽기 /api/mqtt, any role. 이긴 쪽은 Knobs and parameters 절 321~323행 「Read knob state from /api/status」다.
• 596행 HTTP 노브 쓰기 no 와 604행 끝 문장 「wants HTTP for everything except knob writes, and MQTT for those」. 이긴 쪽은 319행 「Both directions work over HTTP」와 POST /api/params 절이다. 표는 절대값(POST /api/params)과 delta(d1..d4)로, 끝 문장은 「can do all of it over HTTP, knob writes included」로.
• 604행 MIDI 가 「the only one with absolute knob values」. POST /api/params 와 MQTT param/N 도 절대값이다. OSC 와 MIDI 둘 중에서라는 뜻이라 「of the two the one」으로.
• 610행 「Errors are {"ok":false,…}」는 모든 오류가 JSON 이라고 읽힌다. 이긴 쪽은 21행 plain-text 404 다. 경로가 없는 404 만 예외라고 한 문장 붙였다. 벡터는 이미 이렇게 갈라 본다: absent-routes.json 은 21행, device-crash.json 과 patterns-select-404.json 은 610행(PR 7).

midi-spec.md:

• 32행 「never echoes a host's messages back」. 이긴 쪽은 Device → host 60행 「by anyone: … MIDI」와 62~64행 「a CC or note the host itself sent」다. 「never echoes a host's CC or note」로 줄이고, 호스트의 Program Change 는 그것이 낸 패턴 바뀜으로 돌아간다고 한 문장 붙였다. out-program-change.json(PR 18)이 그렇게 본다.
• 40행 「two's-complement offset」. 이긴 쪽은 같은 칸의 예(64, 65, 63)와 57행 「binary offset」이다. in-cc-relative.json 의 says 는 예 부분이라 그대로 지나간다.
• 51행 「the audio lanes yield to both」. 「both」를 바로 앞 「relative CCs and notes」로 읽으면 레인을 정한 audio-ws-spec.md 40~49행(버스, 레인, 엔코더 delta 순서, 손이 이긴다)과 엇갈린다. 노트는 노브를 움직이지 않으니 손과 절대 CC 를 뜻한 문장으로 보고 「yield to the hand and to an absolute CC」로 썼다(PR 1 이 적었다).

벡터:

• absent-caps.json: says 를 새 110행으로. 단계는 그대로다.
• state-params-subset.json: says 를 새 165행으로, 그리고 POST /api/params?d2=1 이 200 에 ok:true 인 단계 하나. 다음 단계의 paramActive 가 [true, false, true, false] 그대로라 d2 가 채널을 쥐지 않는 것도 같이 보인다.

증거

로컬, web/:

# 스펙만 고치고 벡터는 아직 그대로인 상태
$ npm run check:rest-vectors | grep -E ": drift|only in|^(passed|failed)"
docs/rest-api-vectors/absent-caps.json: drift
  only in the vector: says docs/rest-api.md
  only in the panel: says not in docs/rest-api.md
docs/rest-api-vectors/state-params-subset.json: drift
  only in the vector: says docs/rest-api.md
  only in the panel: says not in docs/rest-api.md
failed   rest-vectors
$ npm run check:midi-vectors | tail -1
passed   midi-vectors

# 벡터 둘을 다시 옮긴 뒤 (827b253)
$ npm run check:rest-vectors | tail -1
passed   rest-vectors
$ npm run check:midi-vectors | tail -1
passed   midi-vectors
$ npm run check:drift
passed audio-vectors, bom, bom-schematic, changelog, editions, features, links-absolute, markers, midi-vectors, mqtt-vectors, osc-vectors, presets, rest-vectors, shared, virtual-panel
skipped roadmap                        # 원래 레포를 못 읽는다. CI 는 PF_DRIFT_STRICT=1 로 돈다
$ npm run typecheck                    # exit 0
$ npm run lint -- --max-warnings=0     # exit 0
$ python3 ../.github/scripts/check_links.py
all 734 relative links resolve
$ npm run check:human-lock
this diff touches 0 locked files
check:human-lock: no locked words changed
$ npm run check:voice
read: 18 added lines in 2 files
check:voice: nothing found
$ git fetch --tags && npm run doc-map  # CSV 는 git checkout 으로 되돌렸다
1120 links from 224 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 의 새 행 25개는 dev 에 이미 있는 벡터 README 들의 링크다. 이 PR 은 링크를 더하지도 바꾸지도 않는다.

GitHub, 이 PR: head 827b253 에서 「Drift checks / check」(116558933699, PF_DRIFT_STRICT=1) 로그에 passed 열여섯(roadmap, rest-vectors, midi-vectors 포함)과 check:human-lock: no locked words changed. 「Docs point at files that exist / check」(116558798682)도 success. GitHub 이 본 merge 상태는 clean.

실행법

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

가정

• 질문 27 에 창작자 답이 아직 없다(계획서 PR [DONE] 정리 4단계를 PR 스물넷으로 나눈 계획서 — 같이 열릴 수 있는 PR 끼리는 파일이 안 겹친다 #21, 벡터 PR 들 모두 댓글 0). 계획서의 기본값 「그 경로를 정의한 절이 이긴다」로 했다. 창작자가 어느 줄에서 다른 쪽을 고르면 그 줄과 그 줄을 옮긴 벡터만 되돌리면 된다.
• 표가 k23 에 준 파일은 rest-api.md 와 midi-spec.md 다. 같은 꼴의 엇갈림이 둘 더 있지만 파일 밖이라 안 고쳤다: osc-spec.md 18행과 50행(모르는 주소가 호스트를 가르치나, PR 14), mqtt-spec.md 71행과 38·39·45행(Live 에서 스냅숏이 쥔 채널을 knob/N 이 못 움직인다, PR 9). 고치려면 계획서에 행이 있어야 한다.
• 620행 「Utility edition」은 1.3(2026-09-04) 때를 적은 버전 기록이라 두었다. 지금은 491행 「Performance edition」이 맞다(performance 번들에 clock 이 있다).
• 스펙과 펌웨어가 다른 곳은 질문 27 이 아니라 질문 26·28 과 issue 몫이라 안 건드렸다: 250 ms 유예와 800 ms wake guard(PR 6), 손이 아닌 delta 의 5초 잡기, CC 120·121·123, display 의 sleep 이 0/1 인 것, mqttRole 이 MQTT 빌드에서만 나오는 것. 스펙이 말하지 않는 것(requested 가 예시에만, outMul 의 기본값)도 D8 대로 그대로 두었다.
• 버전 기록: 계획서는 「행을 더한다」고 했지만 두 파일 다 아직 안 낸 판의 줄(1.5, 1.2)이 있다. 같은 판 번호를 두 줄로 쓰지 않으려고 그 줄 끝에 한 문장을 붙였다.
• midi-spec.md 133행에 **1.3** (unreleased) 줄이 ## Version history 제목 위에 있고, 머리글은 아직 1.2 다. [DONE] 정리 3단계 PR 2 — 사이트 lint 경고 열둘 중 일곱(img 태그)이 까닭을 적은 예외가 되어 사라진다 #39 때부터 그 자리다. 이 PR 의 일이 아니라 두었고, 그래서 이 PR 의 문장은 머리글이 말하는 1.2 에 붙였다.
• 612행 「the reply then reports the pre-transition state」는 앞으로 더할 핸들러의 규칙이고, select 의 답엔 상태 칸이 없어 38행 수정과 엇갈리지 않는다고 보고 두었다.
• state-params-subset.json 에 단계를 하나 더했다. 계획서는 「re-quotes」라고만 했지만, 165행을 고친 까닭(dN 만의 요청)을 아무 벡터도 보지 않으면 고친 문장이 빈말이 된다. 한 줄이고 펌웨어와도 맞는다.
• 펌웨어와 가상 패널의 오류 문장 「send at least one of p1..p4」는 dN 을 말하지 않지만, 스펙이 그 문장을 정하지 않고 벡터는 <string> 으로만 본다. 그대로다.
• firmware/ 와 web/src/ 를 건드리지 않아 build.sh all, check:ci, check:panels 는 §2.1(1) 대상이 아니다. 화면이 없는 PR 이라 스크린샷은 없다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV 는 안 고쳤고, 라벨은 앞 PR 들처럼 달지 않았다.

Changelog

Docs

• The REST and MIDI specs say one thing where they said two. HTTP writes knobs and reads them from /api/status, select answers with the pattern it queued, d1..d4 alone are a whole POST /api/params, caps names what each edition adds, and only a path no route serves gets a plain-text 404. In midi-spec.md, CC 24–27 are binary offset and a host's Program Change comes back as the pattern change it made.

for an issue

D9: 이 PR 의 벡터가 담은 펌웨어와의 어긋남은 없다. 더한 단계(d2 만의 요청)는 core_status_http.h:649-660 이 쓰기로 센다.

Upstream

• What: Settle the lines where rest-api.md and midi-spec.md contradicted themselves in favour of the route's or message's own section, and bring along the two vectors that quoted a changed line.
• Checks: npm run typecheck, npm run lint, npm run check:rest-vectors, npm run check:midi-vectors and npm run check:drift pass; firmware/ and web/src/ are untouched.
• Docs map: none. No link is added or changed.

🤖 Generated with Claude Code

https://claude.ai/code/session_012EVATQKEEZsieGxy4i6vJQ

---

Generated by Claude Code