[WRONG BRANCH] docs(architecture): name the modules that own the code after the facade splits (#4711)

[lidge-jun]

Summary

The architecture pages and structure/runtime.md still described the module ownership that existed before the facade splits of the last release train, so a reader following them landed in a file that no longer contains the code.

Documented owner	Current owner
server/index.ts for route ordering and the Live sideband	src/server/index/serve-options.ts, with src/server/index/live-sideband.ts for the bounded upstream dial
server/responses/core.ts for body parsing and replay expansion	src/server/responses/request-prepare.ts
server/responses/core.ts for hosted-search binding and helper admission	src/server/responses/passthrough-delivery.ts, src/server/responses/request-sidecar-auth.ts
bridge.ts for SSE and JSON conversion	src/bridge/sse.ts, src/bridge/response-json.ts

src/bridge.ts is seven lines of re-exports. server/index.ts still owns the listener and the startup transaction, and responses/core.ts is still the public ingress, so both keep their entries rather than disappearing — the correction is about which file holds the implementation.

All seven translated locales named the same pre-split files, so fixing only the English source would have left them contradicting it. Each locale gets the same correction.

The facade paragraph also carried three counts — seven, nine and five leaf modules — that were already 26, 42 and 53. A count that must be recounted on every split is a drift source rather than information, so the counts are gone and what replaces them is the distinction they were standing in for: a facade is the stable import path, not the implementation, and each step of the request flow now names the module that owns the code. Every page points at structure/transports/responses.md, which already carries the post-split owner inventory for that surface.

Scope is deliberately narrow. Only claims about which module owns which responsibility change; no prose about behaviour is rewritten, and no locale receives a translation it did not already have. structure/manifest.json is untouched, so structure/INDEX.md needs no regeneration.

Closes #4711

Verification

Local test suites, individual test files, bun run typecheck, bun run test, bun run test:changed, the dashboard build and dependency installation were NOT RUN — the maintainer forbids local suite execution in this lane, since a local test run previously deleted real ~/.opencodex data.

What was done instead, all of it read-only:

• bun scripts/structure-ssot.ts passes (structure/ SSOT checks passed). That is the gate this change is most likely to break: it validates that every backticked repository path exists in the Git index, that relative links and anchors resolve, and that the doc-map, ownership and invariant bindings still hold.
• bun scripts/file-size-ratchet.ts passes against the working tree, which now includes every file this lane adds.
• bun run privacy:scan passes and bun run skill:surface:check reports the committed surface is current.
• Every replaced string was asserted present before substitution, and the script reported no missing target in any of the eight pages or in structure/runtime.md; each page now has exactly two remaining bridge.ts mentions, both deliberate (the module map entry and the facade sentence), and zero remaining server/index.ts or responses/core.ts ownership claims.
• Every newly named path was confirmed tracked with git ls-files before being written into a doc, since structure:check resolves backticked paths against the index rather than the filesystem.

This is the lane tip, so its CI run is the gate for all four layers. The CI run URL and conclusion are reported to the maintainer once it settles.

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.

---

Lane CI evidence (added after the run settled).

This layer's own diff is documentation only, so the ci path filter in ci.yml skips the test matrix for a pull_request event. A green aggregate check on this PR therefore proves nothing about the suite. The lane was gated with a workflow_dispatch run instead, which is not a pull_request event and so runs every job against the cumulative tree:

• Run: https://github.com/lidge-jun/opencodex/actions/runs/35053542913 — completed / success, all 26 jobs green.
• test 1/4, test 2/4, test 3/4, test 4/4 — completed / success (executed, not skipped).
• macos 1/2, macos 2/2, macos control — success. windows 1/6 through windows 6/6 — success.
• gates, storage policy, api usage, docker smoke, keyring (ubuntu/macos/windows), npm-global (ubuntu/macos/windows) — success.

origin/dev was absorbed into the bottom layer and cascaded up the chain, so each PR keeps only its own diff. The dispatch ran on c086fda3a7, whose tree is 3728219b8b5c1758a768108e4b69b648fa0828f6; the current tip baaf691fb4 has the same tree, so the run remains the evidence for this head.

windows 5/6 failed once with EPERM inside removeTreeWithRetry and passed on re-run. That is the pre-existing Windows handle race src/config/paths.ts:57 documents — icacls.exe from hardenConfigDir() holds the config directory open — and the retry loop exists to absorb it. The guard added in the first layer sits outside that loop and never threw; the rethrow came from the pre-existing 50-attempt exhaustion. The same code passed the same test in an earlier dispatch. The load-dependent retry budget is filed separately as #4789.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• ^dev$
• ^preview$

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ff137a2f-bdaa-40f3-b8a0-5f39fee72e47

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-16T02:32:50.870773Z	cf85113	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[lidge-jun]

리뷰 · 우선순위 77 / 80

이 PR은 아키텍처 문서와 structure/runtime.md가 아직도 facade 쪼개기 이전 소유자를 가리키던 문제를 고칩니다. 이슈 #4711이 말한 그대로입니다. 지금 dev HEAD(3070d64d8, 패키지 2.57.0)에는 이미 round5 이후 server/index.ts / responses/core.ts / bridge.ts 가 얇은 진입·재수출 facade로 남아 있고, 실제 라우팅·본문 준비·SSE/JSON 변환은 leaf에 있습니다. 그런데 문서 트리는 여전히 server/index.ts가 HTTP 경계를, responses/core.ts가 JSON 파싱·replay를, bridge.ts가 SSE/JSON을 소유한다고 적혀 있어서, 링크를 따라가면 코드가 없는 파일을 만납니다.

고치는 방식은 좁고 정확합니다. 영어 docs-site/.../reference/architecture.md와 번역 7개(fr/ja/ko/ru/tr/zh-cn/zh-tw), 그리고 structure/runtime.md만 손댑니다. 동작 설명은 다시 쓰지 않고, structure/manifest.json도 안 건드려 INDEX 재생성도 없습니다. 모듈 맵에서는 bridge.ts를 facade로 표시하고 bridge/ leaf(sse.ts / response-json.ts)를 붙입니다. 요청 흐름 1·2·7단계와 Transport/compaction 문단은 server/index/serve-options.ts, server/responses/request-prepare.ts, bridge/sse.ts / bridge/response-json.ts로 바꿉니다. 내가 checkout의 git ls-files로 확인했을 때 이 경로들은 전부 추적 중이고, src/bridge.ts는 실제로 7줄 재수출입니다.

runtime 쪽은 더 세밀합니다. index.ts 표는 리스너·startup 소유로 남기고 route table은 serve-options.ts가 만든다고 덧붙입니다. Responses는 responses.ts / core.ts가 조합만 하고 실제 소유 목록은 이미 맞는 structure/transports/responses.md Core module ownership으로 보냅니다. hosted-search 바인딩은 passthrough-delivery.ts, Chat helper admission은 request-sidecar-auth.ts, Live sideband는 serve-options.ts(핸드셰이크 시작) + live-sideband.ts(bounded dial)로 나눕니다. 이건 #4675/#4677 이후 코드와 맞습니다.

facade 문단에서 예전에 박아 둔 leaf 개수(7·9·5)를 지운 것도 좋습니다. 지금 checkout만 봐도 src/server/responses/*.ts가 이미 수십 개라, 숫자를 문서에 박으면 쪼갤 때마다 또 틀어집니다. 대신 “facade는 안정 import 경로이지 구현이 아니다”와 Responses 소유 목록 링크만 남긴 선택이 맞습니다. 로케일까지 같은 소유자 교정을 한 점도 영어만 고치고 번역이 옛 파일을 가리키는 모순도 피했습니다.

베이스는 dev가 아니라 codex/rg3-ratchet-generated-exemptions입니다. 스택은 #4747(rg1) → #4754(rg2) → #4757(rg3) → 이 팁 #4766(rg4)입니다. MERGEABLE이지만 mergeable_state는 UNSTABLE이고, 지금 Cross-platform CI / hygiene / label / resolve-pr / react-doctor가 아직 queued·pending입니다. 팁 PR이라 이 CI가 네 층 게이트입니다. types.ts/config.ts 분할 캠페인이나 preview deploy와는 무관한 docs-only 소유자 교정이고, godfile/facade가 이미 랜딩된 현재 dev 방향과도 잘 맞습니다. Closes #4711.

architecture.md:1단계 - Live sideband WebSocket join까지 serve-options.ts 한 파일 소유처럼 읽힌다. runtime.md는 live-sideband.ts dial을 따로 적었는데, 아키텍처 흐름 문단은 그 leaf 이름을 안 부른다.
architecture.md 모듈 트리 - bridge/는 트리에 새로 넣었지만 server/index/(serve-options·live-sideband)는 트리에 없어서, 맵과 본문 소유자 표기가 비대칭이다.
architecture.md 요청 흐름 서두 - serve-options.ts가 “HTTP 경계 소유”라고 쓰여 runtime의 “index.ts=리스너/startup, serve-options=route table” 구분보다 한 단계 뭉뚱그려진다. 고의적 요약이면 괜찮지만 초보 독자는 facade와 leaf를 다시 헷갈릴 수 있다.
베이스 브랜치 - dev가 아니라 rg 스택 팁이라, 부모(#4757 등)가 랜딩되기 전에 단독 squash merge하면 순서가 꼬인다.
CI - 리뷰 시점 기준 checks가 아직 pending이라 UNSTABLE이다. docs-only라도 structure:check·ratchet·hygiene가 팁 SHA에서 초록인지 확인이 남는다.

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

• architecture 1단계에 live-sideband.ts를 한 줄 더 넣을지, 아니면 “상세는 runtime/responses 소유 표”로 두고 고수준 흐름은 serve-options만 유지할지
• 모듈 트리에 server/index/를 bridge/와 같이 넣을지(가독성) vs 트리는 얇게 두고 본문·runtime만 정밀하게 둘지
• rg 스택(fix(tests): refuse removals that reach a protected home (#4705) #4747→[WRONG BRANCH] fix(tests): walk the Lab activation chain instead of its first hop (#4704) #4754→[WRONG BRANCH] fix(scripts): name the size exemptions after the reason they exist (#4706) #4757→[WRONG BRANCH] docs(architecture): name the modules that own the code after the facade splits (#4711) #4766)을 통째로 유지한 채 부모부터 랜딩할지, docs-only인 이 팁만 재베이스해 dev에 먼저 올릴지(보통은 스택 유지가 안전)

너의 추천
스택을 유지하고 CI가 팁 SHA에서 통과한 뒤 #4747→#4754→#4757 순으로 랜딩한 다음 이 PR을 머지하세요. 머지 후 #4711은 closes로 같이 닫히게 두면 됩니다. architecture에 live-sideband/index 트리를 더 넣을지는 필수가 아닙니다. 지금 범위(소유자 이름만 교정, 로케일 동기화, 개수 제거, responses.md로 위임)만으로 #4711을 충분히 닫습니다. types/config 분할이나 preview deploy와 무관하니 close-don't-rebase 대상도 아닙니다.

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cf851137ef

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Attribute WebSocket framing to the WebSocket bridge

For the client-facing Responses WebSocket path, src/server/index/websocket-handler.ts passes the SSE response to sendResponseToWebSocket, and src/server/ws-bridge.ts parses those SSE blocks and sends their payloads as WebSocket frames. src/bridge/sse.ts always produces SSE, so assigning both SSE and WebSocket conversion to it gives maintainers the wrong implementation owner; credit src/server/ws-bridge.ts for the WebSocket framing step.

AGENTS.md reference: structure/AGENTS.md:L7-L10

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Include the buffered bridge in compaction ownership

When a routed compaction_trigger request uses stream: false, the buffered branch in src/server/responses/adapter-delivery.ts calls buildResponseJSON(..., { compaction: true }), and src/bridge/response-json.ts emits the synthetic compaction item. Naming only bridge/sse.ts therefore makes this ownership claim false for non-streaming callers; include bridge/response-json.ts here and in the translated copies.

AGENTS.md reference: docs-site/AGENTS.md:L7-L10

Useful? React with 👍 / 👎.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

Landing the repository guard lane, top layer first. Architecture pages now describe the post-facade module ownership, and the facade paragraph drops counts that have to be recounted after every split.

Evidence at the verified tip baaf691 (tree 3728219b8b5c1758a768108e4b69b648fa0828f6), from dispatch run 35053542913:

• test 1-4/4, macos 1-2/2 and macos control all completed with conclusion success, confirmed through the check-runs API rather than the check rollup. windows 1/6 through 6/6 all succeeded, as did gates, storage policy, api usage, docker smoke, keyring and npm-global on three platforms, and the aggregate ci check.
• A dispatch run is the evidence here rather than the pull-request run, and that is not incidental. This lane's tip layer changes only documentation, so the changes path filter skips every heavy job on a pull_request event while the aggregate check still reports green. Because the layers below carry [skip ci], the pull-request signal alone would have covered nothing at all. The dispatch runs against the tip tree, which contains all four layers.
• The dispatch ran at commit c086fda, whose tree is byte-identical to this tip's tree. The lane re-absorbed dev from the bottom layer upward afterwards to keep each pull request's diff to its own layer (5 / 1 / 3 / 9 files); only the merge order changed, so the run remains valid evidence for this tree.
• windows 5/6 failed once with EPERM ... rm ocx-management-auth-* at tests/helpers/remove-tree.ts:38 and passed on re-run. That is pre-existing Windows behaviour, not a regression from this lane: the guard added here runs once before the retry loop, line 38 is the existing rethrow-after-retries path, the raised error is rmSync's EPERM rather than a guard refusal, the identical code passed in run 35050601423, and src/config/paths.ts:57 already documents hardenConfigDir() leaving icacls.exe holding the directory. The retry budget being too small under six concurrent Windows shards is filed separately as [Bug]: the Windows removal retry budget is 2.5 seconds and is exceeded under shard load #4789.
• git merge-tree --write-tree origin/dev <tip> reports a clean merge.
• Ancestry verified so each layer closes as MERGED: rg1, rg2 and rg3 are all ancestors of this tip.

Chained-child stacks merge top-down, so this lands in the parent branch and cascades to dev.

Maintainer integration decision under MAINTAINERS.md / AGENTS.md: a maintainer with maintain or admin access may integrate into dev without a second maintainer approval, recording the decision and exact-head CI evidence.

[github-actions]

⏳ DRAFT

• wrong target branch (codex/rg3-ratchet-generated-exemptions); retarget to dev.

What to do

• Retarget this PR to dev — all contributions go to dev.

Its title has been prefixed with [WRONG BRANCH].
Automatic draft conversion failed (token cannot change draft status). Please convert this pull request to a draft manually. The required enforce-target check will keep failing until every issue above is resolved.