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]

[P2] Keep the lightweight selector out of this exclusion

This renamed acceptance criterion is false on the exact head. apps/desktop/src/renderer/app-shell.tsx:213 statically imports useShellChatModel; apps/desktop/src/renderer/use-shell-chat-model.ts:31-37 then statically imports ./shell-chat-model-selection.js, and apps/desktop/renderer-architecture.json:4306-4310 records that dependency. The same chain remains on current main. The implemented optimization keeps this lightweight selector on the startup path while removing the heavy metadata dependencies. Please describe that actual boundary or remove shell-chat-model-selection.ts from this exclusion, and make the corresponding correction in the Chinese criterion at line 169.

[hqhq1025]

[P2] Reconcile current status with the implemented transport

The new implementation_status: current and last_verified metadata make the unchanged present-tense statement at line 36 inaccurate: the exact-head implementation already plans a turn continuation in packages/runtime/src/model-adapter.ts:281-301, slices to the suffix in openai-responses-continuation.ts:67-82, and sends that delta when the WebSocket request properties match in openai-responses-websocket.ts:280-313. Please mark the problem statement as the pre-optimization state (as the other audited document does) or rewrite it in historical tense before declaring the document current.

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