docs(architecture): audit Model access group against implementation

[ggbdpq]

Summary

Audits the Model access group (2 documents) from #3522 against the current implementation, one PR for the group as requested.

• docs/architecture/openai-responses-incremental-transport.md — every named symbol resolves in the current source: the session-fallback promptCacheKey (maka:${sessionId}) where an explicit caller value wins (packages/runtime/src/openai-responses-continuation.ts:99), the turn-scoped continuation lane in ModelAdapter (model-adapter.ts:145), endLane and the five-minute cross-turn socket cooldown (openai-responses-websocket.ts:118,34), and the sdk.response.messages replay contrast (openai-responses-continuation.ts:37). No drift found, so the only change is the standard frontmatter with last_verified.
• docs/model-metadata-firstscreen-optimization.md — the described optimization is implemented: onboarding:getSnapshot exists, the credential projection is conservatively hasSecret: false (onboarding-service.ts:217), the onboarding hero copy is metadata-free, and the renderer startup chain (app-shell.tsx → use-shell-chat-model.ts → shell-chat-model-selection.ts) carries no runtime metadata import; PROVIDER_REGISTRY remains only under lazy settings paths. The Problem section is therefore now explicitly marked as the 2026-08-04 pre-optimization record, in both languages. One real drift fixed: the cited renderer file chat-model-selection.ts is actually shell-chat-model-selection.ts.

The drift-grep recipes from the tracking issue (run\.json, events\.jsonl, runtime-events\.jsonl, PermissionEngine, respondToPermission, agent-run-store\.test\.ts) return zero matches in both documents.

Verification

Claim	Command / route	Result
Diff is docs-only and scoped to the group	git diff --stat on this branch	2 files, +32/−2
Formatting	npm run format:check	exit 0, 1,942 files clean
License headers	npm run check:asf-headers	all tracked files pass; the only flagged file is my machine's local untracked .gitkeep scratch file, not part of this PR
Symbols in the OpenAI transport doc	grep over packages/runtime/src	all resolve (line refs in Summary)
Startup chain metadata-free	import tracing in apps/desktop/src/renderer	shell-chat-model-selection.ts has zero non-type imports
Drift-grep recipes	the six patterns from the tracking issue	zero matches in both documents

Left untouched on purpose: the point-in-time records (the 2026-08-04 chunk-size tables; the "34 passed" and "3,217 tests" runs in the OpenAI doc's Verification outcome) are historical results of earlier runs and stay as written.

AI use

Prepared with ZCode (GLM-5.3-Flash): the agent read both documents and the current source, traced each claim above to files and lines, and drafted the edits. The commit carries the Generated-by trailer.

Checklist

• One subsystem group only (Model access, 2 documents)
• Refs #3522 in the commit message
• Translations move together (single bilingual file; EN and ZH sections changed in lockstep, translation_status: synced)
• last_verified set to the audit date (2026-09-04)
• Docs only, no code changes

[hqhq1025]

Reviewed exact head 039e93edcae16a0fe37b47f9bb72013ccb4e74a8.

Actual change: adds architecture-document metadata/status text and updates one renderer dependency name. I checked both documents against the exact-head implementation, the current main dependency graph, and the generated renderer architecture ledger.

Validation: hosted test is green; check:asf-headers, check:renderer-architecture, focused Biome formatting, and git diff --check pass. The semantic-continuation unit suite passes 8/8. A broader local runtime build and the WebSocket/model-adapter suites could not run under the reused dependency tree because it has unrelated dependency/type mismatches (@slack/socket-mode missing and an incompatible https-proxy-agent export); I did not treat that local environment failure as PR evidence.

I found two documentation correctness issues inline. I did not independently reproduce the historical startup-size/cold-start measurements.

Automated review notice: This comment was posted by an automated review agent operated by hqhq1025. It is not an independent human review and does not replace one.

[hqhq1025]

Re-reviewed exact head 9ffe10a8b003e0d70649eb76fd438ba4514624df after the merge from main.

The two P2 documentation findings remain on this head:

1. docs/model-metadata-firstscreen-optimization.md:94 and :169 still claim that the startup path excludes shell-chat-model-selection.ts, but app-shell.tsx:216 imports useShellChatModel, which imports that selector at use-shell-chat-model.ts:37; the current renderer architecture ledger records the edge.
2. docs/architecture/openai-responses-incremental-transport.md:36 still describes complete-history upload on every step in present tense while marking the implementation current. The exact-head adapter still plans semantic continuation, selects the suffix, and sends delta input over a matching Responses WebSocket.

The merge commit did not change either PR document relative to the previously reviewed commit; it only brought the branch onto current main. The existing inline threads remain applicable and are not duplicated here.

Validation: hosted test passed on this exact head; renderer architecture passed 101/101; ASF headers and git diff --check passed; the continuation/WebSocket/model-adapter suites passed 28/28 using built artifacts whose relevant source files are byte-identical to this head. The exact-head Runtime build remains blocked in the reused dependency tree by unrelated missing/incompatible dependencies (@slack/socket-mode and https-proxy-agent). I did not reproduce the historical startup performance measurements.

Automated review notice: This comment was posted by an automated review agent operated by hqhq1025. It is not an independent human review and does not replace one.

[hqhq1025]

Re-reviewed exact head 5399a7afba0bfadffd3a5f8a81a8acf9ec31bc2f.

The two previous P2 documentation findings are fixed on this head:

1. docs/model-metadata-firstscreen-optimization.md now accurately states that shell-chat-model-selection.ts intentionally remains on the static startup path as the lightweight selector behind useShellChatModel; the optimization boundary excludes the heavy metadata/catalog modules instead.
2. docs/architecture/openai-responses-incremental-transport.md now marks the Problem section as a historical pre-optimization description and identifies the implemented semantic-continuation and suffix-delta path.

I found no remaining P0-P3 issues. The incremental commit changes only those two documents; the referenced Desktop and Runtime sources are unchanged from the previously inspected head. Hosted test passed on this exact head. Renderer architecture passed 101/101 against the PR base, ASF headers and git diff --check passed, and a synthetic merge onto current main (12ebc45e6fe43b2eebd7dfe61f5c1fa92c0c873a) was clean with an unchanged PR patch. Markdown remains outside the repository's Biome formatting scope. I did not reproduce the historical startup-performance measurements or rerun the full Runtime transport suite for this docs-only correction.

Automated review notice: This comment was posted by an automated review agent operated by hqhq1025. It is not an independent human review and does not replace one.

[Astro-Han]

Thanks for the update. Additional independent review of 5399a7afba0bfadffd3a5f8a81a8acf9ec31bc2f: the earlier corrections are present, but one remaining startup dependency contradicts the completed optimization status. A separate, lower-priority transport eligibility omission is also inline. These are documentation findings; this PR does not introduce a runtime regression.

AI disclosure: Codex agents performed this review; the coordinating agent checked the cited evidence. This is not an independent human review.

中文说明

此前两处修正已经在当前提交中；本轮另外发现首屏静态依赖仍存在，完成状态不准确，以及一处 transport 适用范围遗漏。均为文档问题，不是本次引入的运行时回归。

[Astro-Han]

Thanks for the change. Approving exact head 09dfe11d85db463b078387870fb03c5e9f29344e following the completed review and Astro-Han’s explicit acceptance of this merge batch. Current checks pass and no review threads remain unresolved.

Align model-access documentation with implemented Responses continuation and startup behavior. Explicitly retain the command-palette metadata dependency as an incomplete acceptance boundary and document customized-request transport exclusions. Documentation only; remaining runtime debt is not claimed fixed.

AI assistance: Codex performed the review and final-state verification; Astro-Han authorized approval and merge.

中文

感谢改动。基于已完成的审查和 Astro-Han 对本批次的明确认可，批准当前精确 head；检查通过，讨论已结清。此前说明的验证边界与后续事项保持不变。本次由 Codex 执行审查和状态核对，Astro-Han 授权批准与合并。