fix(responses): align Spark Lite metadata with serialized body

[lidge-jun]

Summary

Derive canonical Spark Responses Lite headers and WebSocket metadata from the body actually serialized. A surviving nonempty additional_tools.tools array pins Lite to true; other Spark bodies pin it to false. Header casing, stale native metadata, aliases and configured bracket-suffix removal use the final wire model. Other models and noncanonical configured headers retain their policy.

Carries #4130 with its latest bidirectional body-shape correction and resolves the remaining empty-group documentation finding across eight locales. Adds post-filter catalog, reserved-functions, top-level-tools, bracket normalization and noncanonical header coverage alongside the author's socket-retirement/reuse tests. This proves the intended framing contract once CI passes; it does not claim a live provider EOF fix.

Spark remains available. #4334 retirement is a separate HOLD and is not included. No running service or user configuration was changed. Independent ordinary dev-based PR; source PR disposition after integration belongs to the coordinator.

Verification

• Local product suites/build/typecheck/install: NOT RUN, explicitly prohibited. Push uses --no-verify.
• git diff --check and the documentation/source-map validator bun scripts/structure-ssot.ts: passed. These are source checks, not product tests.
• Independent design reflection and A audit: PASS after three amendments. Implementation review and final-head hosted CI are tracked after publication.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Co-authored-by: luvs01 27862058+luvs01@users.noreply.github.com

Current head: 4b8eaed3449b4e10dd67aefd0b6e9b0bfe06005e, rebased onto e4ee8c54b0d3dcf5d245aea4589d608bf118c9c3. Independent implementation/security and resolution-only audits PASS; adapter, transport dependencies and both tests byte-identical to reviewed product commit. Source credits retained. Local product checks NOT RUN; refreshed hosted CI pending.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 66 / 80

이 PR은 Spark Responses Lite 헤더·WebSocket 메타데이터를, 실제로 직렬화되는 body 모양에 맞춥니다. body에 비어 있지 않은 additional_tools.tools 배열이 남아 있으면 Lite를 true로 고정하고, 그 외 Spark body는 false로 고정합니다. 모델 suffix bracket strip도 메타데이터 도출 전에 적용해, HTTP 헤더와 WS client_metadata가 같은 wire model을 보게 합니다. 원본 기여는 luvs01 공동이고, thinking_contract 플랜 문서가 같이 들어 있습니다.

버그의 실체는 이렇습니다. Spark 카탈로그는 도구를 top-level tools가 아니라 Lite 모양(input[].additional_tools)으로 실어 보냅니다. 예전에 Lite를 헤더에서 지우거나 상속 false를 남겨 두면, 프레임은 non-Lite라고 광고하면서 도구는 Lite 슬롯에만 있어 Spark가 도구를 잃습니다. 반대로 도구 없는 Spark 스트림은 Lite를 끄지 않으면 조기 종료 문제가 남습니다. 이 PR은 body가 결정하게 해 두 경우를 갈랐습니다.

코드 변경의 중심은 src/adapters/openai-responses.ts의 bodyCarriesLiteToolShape와 Spark 분기입니다. 테스트가 HTTP·WS 메타데이터 동기화, Lite-shaped pin-on, malformed metadata fallback, 소켓 identity 재사용까지 덮습니다. 다만 additions 1070 중 상당수는 devlog/_plan/260912_thinking_contract/*와 다국어 architecture docs입니다.

라인 / 심볼 - bodyCarriesLiteToolShape - nonempty tools 배열만 Lite로 인정. 빈 additional_tools는 false → 스트림 픽스 의도. 맞음
경로/심볼 - bracket strip 시점 이동 - finalBody 정규화 후 stringify. 다른 모델·noncanonical 헤더 경로는 유지되는지 테스트에 있음
경로/심볼 - thinking_contract 플랜 md 대량 추가 - Spark 픽스와 직접 무관한 문서 무게. 같은 PR에 둘지 분리할지
경로/심볼 - 다국어 architecture.md +7~9줄 - 번역 드리프트·충돌 비용
경로/심볼 - mergeable UNKNOWN - tip과 dev 최근 responses 변경(#4350 continuation 등) 충돌 여부 재조회 필요

메인테이너의 판단이 필요한 지점

• 런타임 픽스만 먼저 랜딩하고 thinking 플랜 문서는 후속으로 뺄지
• Spark 이외 모델에 비슷한 Lite/body 불일치가 더 있는지 감사 범위
• draft 유지 기간(CI·충돌 확인)

너의 추천
기능 자체는 dev에 넣을 만하다. tip mergeable을 확인하고 metadata·ws-upstream 테스트가 초록이면 draft 해제. 플랜 md/번역 노이즈가 충돌을 만들면 코드+테스트만 남긴 얇은 PR로 다시 올린다. 중복 Spark Lite PR이 있으면 이 본문 정렬 버전을 남기고 나머지는 close.

이 댓글은 grok-bot이 작성했습니다

[github-actions]

⏳ DRAFT

• UI screenshot required.

What to do

• Add a screenshot of the UI change to the PR description.

This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.