From 039e93edcae16a0fe37b47f9bb72013ccb4e74a8 Mon Sep 17 00:00:00 2001
From: ggbdpq <ggbdpq@gmail.com>
Date: Fri, 4 Sep 2026 23:50:59 +0800
Subject: [PATCH 1/2] docs(architecture): audit Model access group against
 implementation

Audit the two Model access documents from the #3522 documentation
audit against the current implementation.

openai-responses-incremental-transport.md: every named symbol resolves
in the current source (session-fallback promptCacheKey with explicit
value winning, turn-scoped continuation lane, endLane release, the
five-minute cross-turn socket cooldown, the sdk.response.messages
replay contrast). No drift; added the standard frontmatter with
last_verified.

model-metadata-firstscreen-optimization.md: the described optimization
is implemented (onboarding:getSnapshot projection, conservative
hasSecret:false, metadata-free onboarding hero copy, startup chain
verified metadata-free), so the Problem section is now explicitly
marked as the 2026-08-04 pre-optimization record in both languages.
Fixed the cited renderer file name chat-model-selection.ts to the
actual shell-chat-model-selection.ts. Added the standard frontmatter.

The drift-grep recipes from the tracking issue return zero matches in
both documents.

Refs #3522

Generated-by: GLM-5.3-Flash (ZCode)
---
 .../openai-responses-incremental-transport.md | 12 ++++++++++
 ...model-metadata-firstscreen-optimization.md | 22 +++++++++++++++++--
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/architecture/openai-responses-incremental-transport.md b/docs/architecture/openai-responses-incremental-transport.md
index 162c736641..38f2553a1b 100644
--- a/docs/architecture/openai-responses-incremental-transport.md
+++ b/docs/architecture/openai-responses-incremental-transport.md
@@ -1,3 +1,15 @@
+---
+doc_id: architecture.openai-responses-incremental-transport
+title: "OpenAI Responses incremental transport"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: source-only
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/model-metadata-firstscreen-optimization.md b/docs/model-metadata-firstscreen-optimization.md
index b021a802a4..99984e0626 100644
--- a/docs/model-metadata-firstscreen-optimization.md
+++ b/docs/model-metadata-firstscreen-optimization.md
@@ -1,3 +1,15 @@
+---
+doc_id: model-metadata-firstscreen-optimization
+title: "perf(desktop): remove models.dev metadata from the renderer startup path"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -24,6 +36,10 @@
 
 ## Problem
 
+> **Status (verified 2026-09-04):** this optimization is implemented — every one of the five startup
+> import paths listed below is cut in the current source. The Problem is kept as the 2026-08-04
+> record of the pre-optimization state.
+
 Most users configure only a few providers, but Maka currently loads metadata for every provider and hundreds of models on startup. This data should remain behind the main-process authority boundary, with the renderer receiving only the lightweight projection needed for the current UI.
 
 The Desktop AppShell startup path statically loads `packages/core/src/model-metadata.generated.ts`. The file is generated during installation or build from the committed models.dev snapshot; the 2026-08-04 measurement below was about 520 KB / 13,988 lines and contained full metadata for roughly 44 providers and hundreds of models.
@@ -75,7 +91,7 @@ Full metadata remains available to the main process and lazy-loaded SettingsModa
 Acceptance criteria:
 
 - The startup entry and all of its static transitive dependencies exclude `model-metadata.generated.ts`, `model-metadata.ts`, `provider-registry.ts`, `model-catalog.ts`, and `model-thinking.ts`.
-- The startup path no longer statically depends on the renderer's `model-catalog-choices.ts` or `chat-model-selection.ts`.
+- The startup path no longer statically depends on the renderer's `model-catalog-choices.ts` or `shell-chat-model-selection.ts`.
 - Searching startup chunks for `claude-opus|gpt-5\.|gemini-2\.` returns zero; full metadata exists only on lazy Settings paths.
 - Model choices, headings, provider logos, and active/new-chat thinking levels remain correct.
 - OnboardingHero still shows the four recommended providers with their names, descriptions, and logos.
@@ -97,6 +113,8 @@ Acceptance criteria:
 
 ## 问题
 
+> **状态（2026-09-04 核验）：** 该优化已落地——下面列出的五条首屏依赖链在当前源码中均已切断。Problem 一节保留的是 2026-08-04 优化前状态的记录。
+
 大多数用户只配置少数几个 provider，但 Maka 当前会在启动时加载全部 provider 和数百个模型的元数据。完整目录应留在 main process 的权威边界内，renderer 只接收当前界面所需的轻量投影。
 
 桌面端 AppShell 的首屏静态依赖会加载 `packages/core/src/model-metadata.generated.ts`。该文件在安装或构建时由 committed models.dev snapshot 生成；下面记录的 2026-08-04 实测约为 520 KB、13,988 行，包含约 44 个 provider 和数百个模型的完整元数据。
@@ -148,7 +166,7 @@ Session health notice 在 event 触发的异步刷新完成前继续使用上一
 验收标准：
 
 - 首屏入口及其所有静态传递依赖不包含 `model-metadata.generated.ts`、`model-metadata.ts`、`provider-registry.ts`、`model-catalog.ts` 或 `model-thinking.ts`。
-- 首屏不再静态依赖 renderer 的 `model-catalog-choices.ts` 和 `chat-model-selection.ts`。
+- 首屏不再静态依赖 renderer 的 `model-catalog-choices.ts` 和 `shell-chat-model-selection.ts`。
 - 构建产物的首屏 chunk 中检索 `claude-opus|gpt-5\.|gemini-2\.` 为 0；完整元数据只存在于设置页懒加载路径。
 - model picker 的模型、heading、provider logo，以及 active/new-chat thinking level 选项保持正确。
 - OnboardingHero 正常显示 4 个推荐 provider 的名称、描述和 logo。

From 5399a7afba0bfadffd3a5f8a81a8acf9ec31bc2f Mon Sep 17 00:00:00 2001
From: ggbdpq <ggbdpq@gmail.com>
Date: Sat, 5 Sep 2026 21:01:17 +0800
Subject: [PATCH 2/2] docs: correct the startup-path exclusion and mark the
 transport problem historical

Two review (hqhq1025) findings on this audit:

- model-metadata-firstscreen-optimization.md claimed the startup path no
  longer statically depends on shell-chat-model-selection.ts, but
  app-shell.tsx imports useShellChatModel, which statically imports that
  selector (use-shell-chat-model.ts). The selector is the lightweight piece
  the optimization intentionally keeps; only the heavy metadata modules and
  model-catalog-choices.ts moved off the startup path. State that boundary in
  both the English and Chinese criteria.
- openai-responses-incremental-transport.md declared current status while its
  Problem section stayed in present tense. Add the same implemented-status
  banner the sibling document uses, marking the Problem text as the
  pre-optimization record.

Generated-by: GLM-5.3-Flash (ZCode)
---
 docs/architecture/openai-responses-incremental-transport.md | 6 ++++++
 docs/model-metadata-firstscreen-optimization.md             | 4 ++--
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/architecture/openai-responses-incremental-transport.md b/docs/architecture/openai-responses-incremental-transport.md
index 38f2553a1b..3713127451 100644
--- a/docs/architecture/openai-responses-incremental-transport.md
+++ b/docs/architecture/openai-responses-incremental-transport.md
@@ -33,6 +33,12 @@ owners:
 
 ## 1. Problem and invariant
 
+> **Status (verified 2026-09-04):** this optimization is implemented — the adapter plans a turn
+> continuation and sends the suffix delta over a matching Responses WebSocket
+> (`packages/runtime/src/model-adapter.ts`, `openai-responses-continuation.ts`,
+> `openai-responses-websocket.ts`). The Problem below is kept as the record of the
+> pre-optimization state.
+
 Long tool loops currently rebuild and upload the complete provider history on every step. The
 durable Runtime event ledger remains the source of truth, but the OpenAI Responses transport may
 reuse a turn-scoped WebSocket and send only the suffix after the previous response.
diff --git a/docs/model-metadata-firstscreen-optimization.md b/docs/model-metadata-firstscreen-optimization.md
index 99984e0626..ac8c33f52c 100644
--- a/docs/model-metadata-firstscreen-optimization.md
+++ b/docs/model-metadata-firstscreen-optimization.md
@@ -91,7 +91,7 @@ Full metadata remains available to the main process and lazy-loaded SettingsModa
 Acceptance criteria:
 
 - The startup entry and all of its static transitive dependencies exclude `model-metadata.generated.ts`, `model-metadata.ts`, `provider-registry.ts`, `model-catalog.ts`, and `model-thinking.ts`.
-- The startup path no longer statically depends on the renderer's `model-catalog-choices.ts` or `shell-chat-model-selection.ts`.
+- The startup path no longer statically depends on the renderer's `model-catalog-choices.ts`; `shell-chat-model-selection.ts` deliberately remains on the static path as the lightweight selector behind `useShellChatModel` — this optimization removes the heavy metadata modules, not that selector.
 - Searching startup chunks for `claude-opus|gpt-5\.|gemini-2\.` returns zero; full metadata exists only on lazy Settings paths.
 - Model choices, headings, provider logos, and active/new-chat thinking levels remain correct.
 - OnboardingHero still shows the four recommended providers with their names, descriptions, and logos.
@@ -166,7 +166,7 @@ Session health notice 在 event 触发的异步刷新完成前继续使用上一
 验收标准：
 
 - 首屏入口及其所有静态传递依赖不包含 `model-metadata.generated.ts`、`model-metadata.ts`、`provider-registry.ts`、`model-catalog.ts` 或 `model-thinking.ts`。
-- 首屏不再静态依赖 renderer 的 `model-catalog-choices.ts` 和 `shell-chat-model-selection.ts`。
+- 首屏不再静态依赖 renderer 的 `model-catalog-choices.ts`；`shell-chat-model-selection.ts` 作为 `useShellChatModel` 背后的轻量选择器有意保留在静态路径上——本优化移除的是重量级元数据模块，不含这个选择器。
 - 构建产物的首屏 chunk 中检索 `claude-opus|gpt-5\.|gemini-2\.` 为 0；完整元数据只存在于设置页懒加载路径。
 - model picker 的模型、heading、provider logo，以及 active/new-chat thinking level 选项保持正确。
 - OnboardingHero 正常显示 4 个推荐 provider 的名称、描述和 logo。