Repository navigation
[Docs]: architecture pages still describe the pre-facade-split module ownership #4711
Description
Documentation problem type
Outdated documentation
Documentation location
docs-site/src/content/docs/reference/architecture.md (and its translated locales) plus structure/runtime.md
What is wrong or missing?
Both pages still describe the module ownership that existed before the facade splits of the last release train. Between v2.55.0 and 2.56.0, twelve large modules were split behind facades, and the architecture tree in these pages was not updated with them.
Concretely: routing now lives in src/server/index/serve-options.ts, request preparation in src/server/responses/request-prepare.ts, and bridge conversion in src/bridge/sse.ts. The pages point at the pre-split files instead. The translated locales carry the same stale description, so fixing only the English source would leave them contradicting it.
This is documentation drift, not a runtime problem — it was found during the 2.56.0 regression audit and recorded there rather than fixed inside a release change.
What should the documentation explain instead?
The architecture tree and the ownership text should name the modules that own each responsibility at the current tip, so a reader following the page lands in the file that actually contains the code. structure/transports/responses.md already carries the post-split owner inventory for the responses surface and can be used as the reference for that part.
Suggested wording or example
Use the owner table in structure/transports/responses.md ("Core module ownership") as the shape: one row per owner, one sentence of responsibility. Update the English source first, then bring ja, ko, fr, ru, tr, zh-cn and zh-tw onto it so no locale contradicts the source.
Additional context or attachments
Found during the 2.56.0 release audit; recorded in devlog/_plan/260915_2560_release_train/020_regression_audit.md among the accepted risks.
Checks
- I searched existing documentation issues.
- No secrets or personal information are included.
Activity
lidge-jun commentedon Sep 15, 2026
리뷰 · 우선순위 68 / 80
이 이슈는 문서가 파사드 스플릿 이전 모듈 소유권을 그대로 적어 둔 문서 드리프트다. 현재
devHEAD는51d577c3f(#4700, 패키지 2.57.0)이고, 2.55→2.56 구간에서 responses/core·bridge·server/index·openai-responses 등 열두 개 큰 모듈이 파사드 뒤로 갈라졌다. 그런데docs-site/src/content/docs/reference/architecture.md는 여전히 트리에bridge.ts·server/index.ts·server/responses/core.ts를 본체로 적고, 본문 단계 설명도 그 경로를 따른다.structure/runtime.md도src/adapters/openai-responses.ts·bridge.ts·src/server/responses/core.ts를 소유자로 남긴 줄이 있다. 런타임 버그는 아니고, 읽는 사람이 옛 파일로 들어가게 만드는 문제다.이슈가 가리킨 새 소유자는 tip과 맞다. 라우팅·서빙 옵션은
src/server/index/serve-options.ts에 있고, 요청 준비는src/server/responses/request-prepare.ts쪽, 브리지 변환은src/bridge/sse.ts등 leaf로 갈라져 있다.structure/transports/responses.md의 Core module ownership 표는 이미 스플릿 이후 모양이라 영문 architecture와 runtime을 그 표 기준으로 맞춘 뒤 ja/ko/fr/ru/tr/zh-cn/zh-tw를 따라가게 하면 로케일 모순을 막을 수 있다. 회귀 감사(devlog/_plan/260915_2560_release_train/020_regression_audit.md)에서 받아 둔 리스크를 이슈로 남긴 형태라, 제품 freeze와 충돌하지 않는 docs-only 후속이다.우선순위는 중상이다. 초보 기여자가 잘못된 모놀리스 경로에 PR을 열면 close-don't-rebase 비용이 다시 생긴다. 반대로 동작 회귀는 없으므로 핫픽스 대상은 아니다. types.ts/config.ts 스플릿 캠페인과도 별개다.
경로
docs-site/src/content/docs/reference/architecture.md- 트리·단계 설명이 pre-splitcore.ts/bridge.ts/server/index.ts소유권을 그대로 가리킨다.경로
structure/runtime.md-openai-responses.ts·bridge.ts·responses/core.ts서술이 현재 leaf 배치와 어긋난다.경로
structure/transports/responses.md- 이미 post-split owner 표가 있어 이 이슈의 기준 문서로 쓸 수 있다.경로 번역 로케일 - 영문만 고치면 ja/ko 등이 옛 경로를 남겨 서로 모순된다.
메인테이너의 판단이 필요한 지점
너의 추천
docs-only PR로 받아라. 영문
architecture.md와structure/runtime.md를structure/transports/responses.mdowner 표에 맞춘 뒤, 번역 로케일을 같은 변경으로 따라가게 한다. 코드 변경·미리보기 배포는 필요 없다.이 댓글은 grok-bot이 작성했습니다
Merge pull request #4766 from lidge-jun/codex/rg4-ownership-docs
lidge-jun commentedon Sep 16, 2026
Landed via #4766 at 3b52c0a
lidge-jun commentedon Sep 16, 2026
Landed via #4766 at cf85113
docs(architecture): name the modules that own the code after the faca…
docs(architecture): name the modules that own the code after the faca…
Merge pull request lidge-jun#4766 from lidge-jun/codex/rg4-ownership-…