Proposal: make default flips safe for pre-existing durable state (bounded first upload, auxiliary-field isolation, upgrade-path guardrails)

[donyue7]

Context

Follow-up to the repeated reports of large sessions getting permanently stuck on HTTP 413 at the official DeepSeek API once the session-log upload became default-on (see the prior-art table below).

Stripped of its specifics, that bug is an instance of a general pattern that this codebase is structurally exposed to:

default flip × pre-existing durable state × fail-closed side effect

1. A release changes a plugin's default configuration (here: off → on).
2. That plugin consumes durable state written by earlier releases (here: session logs from ≤ 0.1.6, which therefore carry no acceptance watermark).
3. Its cold-start behavior on that state is unbounded (upload everything) and its failure mode is fail-closed (a rejected auxiliary field fails the whole model request, and the cursor never advances), so the very first request after the upgrade can put the user into a permanent, self-healing-impossible state — with no UI signal pointing at the auxiliary field.

Nothing exotic is required: no third-party plugin, no unusual configuration. Every user who upgrades with a large enough session hits it. The same shape is reachable from other durable-state consumers (projection caches, storage domains, workspace registry, telemetry prefixes, plugin inventories) whenever a default flips.

This proposal asks for three guardrails. They are independent; P2 alone would have prevented the stuck state, and it is the smallest change.

P1 — Stateful activation contract (plugin level)

A plugin whose behavior depends on durable state written before it was active must declare and implement its cold-start contract, and the loader/review checklist must require it:

• Bounded first payload. When no watermark/baseline exists for the current state, the first delivery must be bounded — e.g. the most recent N events or maxBytes, plus an explicit truncatedFrom / baselineSeq marker telling the receiver that earlier content was intentionally omitted. "No watermark ⇒ send everything" must not be a legal implementation.
• Observable baseline. Record a durable marker when the baseline is established (e.g. …/baseline-established), so "this session has never uploaded" is distinguishable from "this session uploaded and is current".
• Opt-in activation for pre-existing state. A default that turns on consumption of pre-existing state is a migration, not a default. Either keep it off until an explicit migration step runs, or ship the flip with the bounded-first-payload guarantee above.

P2 — Auxiliary-field isolation (adapter level)

Registered auxiliary top-level fields (ctx.deepseekLlmApiExtensions today, potentially others later) are metadata contributions to a model request. A metadata contribution must never be able to make the model request permanently unusable.

• Byte budget. Give the composed auxiliary payload an enforced budget (per field and total). Overflow is a field failure, not a request failure.
• Degrade, then retry once without the field. On a 4xx that the adapter cannot attribute to the model input (413/400 body-size class), re-send the same request without the auxiliary fields. The user still gets their answer; the field reports the failure.
• Per-session circuit breaker with a durable marker and a surface. After a field causes a rejection, stop attaching it for that session (persist …/delivery-blocked with the reason and the offending size) and tell the user once — instead of the current behaviour, where the session silently 413s forever and only shows DeepSeek Messages request failed (413).
• Invariant companion. This repo already uses invariant companions for continuously observable relations; an auxiliary contribution is one: "a registered auxiliary field never changes whether the model request succeeds." A companion can assert the budget and the degrade-before-fail ordering.

P3 — Upgrade-path guardrails (release and CI level)

• Machine-readable tree diff between releases. dsh --dump-config already renders the composed profile; a companion mode (dsh upgrade-check --from <version> or --diff <dump>) should print, for the previous and current release: entries whose defaults changed, entries newly enabled, and entries that consume pre-existing durable state. This is exactly the check that was missing: the 0.1.7 release notes could not tell a user "this upgrade will start uploading your entire session history".
• Upgrade-path fixture in CI. Build a home from the previous release containing representative state (a large session, storages, credentials), upgrade to the candidate build, then assert: (i) the app boots, (ii) one request per provider route completes on the pre-existing session, (iii) the serialized request body stays under an enforced maximum.
• Size invariant on the wire path. Put the maximum request body size in one place and assert it for every request the adapters build, auxiliary fields included. That turns "no independent request-size cap" from a documented limitation into a tested invariant.
• Release-note obligation. Any default flip that changes on-disk or on-wire behaviour for existing state is called out in the release notes with its rollback path (enabled: false overlay).

Prior art behind this proposal

The pattern is not hypothetical and not a single user's environment — the tracker already holds several independent reports of it, plus a code-level confirmation:

Report	Angle
#6754	0.1.6 turned the upload on by default; ~260 MiB request bodies; asks for default-off + explicit consent
#6862	first upload carries the entire log; corroborated on a second machine/build (three sessions deadlocked from the upgrade restart)
#7247	fork inherits the whole log; upstream body limit ≈ 50 MB
#7658	V3→V4 (and "never established") watermark invalidation; confirmed at HEAD by a maintainer-side reply pointing at session-log-deepseek/src/index.ts:136
#7626	compaction cannot rescue it — the summarization request hits the same limit; 413 is classified as INVALID_REQUEST, so the context-window recovery path never fires
#6816 / #7220	bare 413 normalization and the observability gap (status code survives, provider body does not)

Additional evidence contributed under #7658: a machine-verified default diff (0.1.5-rc.2 enabled: false → 0.1.7-rc.1 enabled: true), the never-established-watermark measurements, and a workaround verified end-to-end after a restart.

Six weeks of independent reports, one confirmed mechanism: the case for the guardrails below is not a new feature request, it is a request to make an existing, repeatedly-hit class of failure impossible.

Suggested order of work

Order	Item	Why first
1	P2 (budget + retry-without-fields + circuit breaker)	Smallest change; converts a permanent deadlock into a visible, recoverable degradation
2	P1 (bounded first payload + baseline marker) for dsh-session-log-deepseek	Removes the trigger entirely for existing sessions
3	P3 (upgrade-check + CI fixture + size invariant)	Prevents the whole class, not just this instance

Question for maintainers

Would you accept a PR for P2, and/or for the P3 upgrade-check diff mode? I can start with whichever fits your roadmap; a first cut of P2 (budget + one retry without auxiliary fields + a per-session blocked marker) looks self-contained inside dsh-llm-deepseek + the extensions registry.

[yamingmou]

Three readings of published artifacts, about the guardrails in this proposal. Two are about what is already on the wire; the third is about where a release-level diff has to be taken to answer the question it is meant to answer.

1. The byte bound has landed on one field; the request body still has none

dsh-session-log-deepseek@0.1.7-rc.2 carries a byte bound on the field it contributes. maxBytes defaults to 8 * 1024 * 1024 (lib/index.js:19). The contribution walks events forward from the acceptance marker and stops at the first one that would cross the bound (:161); if even the first event does not fit, it contributes nothing and records that through logger.warn (:166-172); the marker advances only inside accept() (dsh-session-log-deepseek:181-187), and the adapter invokes that acceptance transaction only after a 2xx (dsh-llm-deepseek:2214). So on this field, "no marker ⇒ send everything" is no longer a reachable implementation — which is the strongest half of the proposal's first item.

Two details differ from that item's wording. The bound is on the contributed field's own bytes, not on the composed request body, which still has no bound of its own. And the events taken are the oldest run rather than the most recent N: accumulation starts at afterSeq + 1 and walks forward (:143, :157-164).

The third bullet of that item is not addressed in rc.2: activation is still enabled: default(true), and the plugin returns early only when it is not true (:136).

2. On the three P2 items: one is closer than it looks, two are absent

I read both halves of that path — the adapter (dsh-llm-deepseek@0.1.7-rc.2) and the registry (dsh-deepseek-llm-api-extensions@0.1.7-rc.2) — from published tarballs.

Budget, per field and total: absent on both sides. The registry prepares every registered field in parallel and clones and freezes the values (extensions:70-91); no size contract appears in it. The adapter stringifies { ...body, ...extensions.fields } (llm-deepseek:1355) and posts it (:2186) without measuring it. The only byte budgets on this request path are for images, against maxInlineRequestImageBytes and maxRequestFilesBytes (:244, :1381-1388). A whole-body ceiling with field-drop accounting is published as a reference implementation in #7820; what follows is about the shipped artifacts, where neither layer is present.

This is worth separating from item 1. The bound that exists today is a provider bounding its own field. The registry admits exactly one provider per field name and imposes no size contract, so a second auxiliary field is not constrained by anything the first one did.

Degrade, then re-send without the field: the mechanism exists, the trigger does not. prepareRequestExtensions already falls back to the base request with every contributed field dropped, and that fallback does three things: it reports the omitted field names through onOmitted (:1361), it returns the base payload alone (:1363), and it makes accept a no-op (:1364) so contributors re-send their unaccepted state on a later request. The trigger is a failure to serialize the merged payload (:1353-1366). The HTTP error path is separate and drops nothing: on a non-2xx the adapter parses the body, gives files.retry(detail) its chance, and otherwise throws (:2200-2213) — and that retry returns true only when a file is in use and the provider's error classifies as a stale id, and only once per request (:1305-1315). So re-sending without the auxiliary fields would extend a path that already exists rather than add machinery, which is consistent with the proposal's own note that this item is the smallest of the three.

Circuit breaker, durable marker, surface: absent. Neither package mentions a breaker or a blocked state, and the only trace left when a field is dropped is a logger.warn on the serialize-failure path (:2252-2253). Nothing per session, nothing durable, nothing user-facing.

For completeness on the classification item: the branch that maps 400 and 413 to INVALID_REQUEST is identical in rc.1 and rc.2 (:1748-1749).

3. A release-level diff has to be taken against published artifacts

The third guardrail's example is that release notes could not tell a user "this upgrade will start uploading your entire session history". The tree can be read for that; the tree is not where the answer lives. One case from the published set of @deepseek-ai/dsh-subagent:

• Last published artifact carrying 2: 0.1.1-rc.2 — 2026-08-21T12:32:59Z.
• f76a225a7d merges; the descriptor constant becomes 3 on master — 2026-08-24.
• First published artifact carrying 3: 0.1.2-alpha.2 — 2026-08-30T14:02:58Z.
• Releases between those two artifacts: none.

Between those dates master and the newest installable artifact disagree — 3 against 2 — so a diff keyed on merge dates reports a change as in effect up to six days before any user can receive it. The same holds for "which version first contains X": only a per-version sweep of published artifacts answers it, because the tree does not express which versions are reachable by install. The version a default install resolves to is a second input that a tree diff has no view of at all.

Boundary: I read published tarballs and registry metadata on 2026-09-25 and executed nothing. The CI-fixture and wire-invariant parts of that guardrail are not verifiable from outside a checkout. I have not re-opened the threads in the prior-art table. Line numbers are from the rc.2 tarballs named above; the constant history is from npm's published version list for @deepseek-ai/dsh-subagent.

Authorship note: the readings above were taken by me against published npm artifact tarballs and registry metadata; drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out; I will re-verify against the toolchain and correct.

Reported by the OfferKuai Team — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/ | Contact: contact@offerkuai.com

---

中文版

三条都是对已发布产物的读法，针对提案里的三条护栏。前两条讲"线上到底已经做到了什么"，第三条讲"要回答发布级 diff 想回答的那个问题，diff 该取在什么地方"。

1. 字节界已经落在一个字段上；请求体仍然没有

dsh-session-log-deepseek@0.1.7-rc.2 对它贡献的那个字段带了字节界。maxBytes 默认 8 * 1024 * 1024（lib/index.js:19）。贡献逻辑从接受标记处向后逐事件累加，遇到第一个会越界的事件就停（:161）；若第一个事件就放不下，则不贡献，并通过 logger.warn 留下记录（:166-172）；标记只在 accept() 内推进（dsh-session-log-deepseek:181-187），而适配器只在 2xx 之后才调用这组接受事务（dsh-llm-deepseek:2214）。⇒ 在这个字段上，"没有标记就发全部"已不是可达的实现 —— 这正是提案第一项里最强的那一半。

有两处细节与那一项的措辞不同。这个界是贡献字段自身的字节，不是组合后的请求体 —— 请求体本身仍然没有界。取的事件是最旧的一段连续前缀，不是最近 N 条：累加从 afterSeq + 1 起、向前走（:143、:157-164）。

那一项的第三条在 rc.2 里没有被回应：激活仍是 enabled: default(true)，插件只在其不为 true 时提前返回（:136）。

2. 关于 P2 的三项：一项比看起来更近，两项不在

这条路径的两半我都读了 —— 适配器 dsh-llm-deepseek@0.1.7-rc.2 与登记处 dsh-deepseek-llm-api-extensions@0.1.7-rc.2 —— 都取自已发布 tarball。

预算（逐字段与总量）：两侧都没有。 登记处把每个已注册字段并行准备、把值克隆并冻结（extensions:70-91），里面没有尺寸契约。适配器把 { ...body, ...extensions.fields } 序列化（llm-deepseek:1355）后直接投递（:2186），全程不量尺寸。这条请求路径上唯一的字节预算在图片侧，对照的是 maxInlineRequestImageBytes 与 maxRequestFilesBytes（:244、:1381-1388）。带字段级丢弃记账的整包体上限，已作为参考实现发布在 #7820；下面讲的是已发布产物，这两层在其中都还没有。

这一点要与第 1 条分开看：今天存在的界，是提供方给自己那个字段加的界。登记处对每个字段名只接纳一个提供方，且不施加任何尺寸契约 —— 所以第二个辅助字段不受前一个做过什么的约束。

降级 / 去掉字段重发：机制已在，触发条件不在。 prepareRequestExtensions 已经有"退回纯 base 请求、把所有贡献字段全部去掉"的降级，且它在这一路径上做三件事：通过 onOmitted 上报被省略的字段名（:1361）、只返回 base 载荷（:1363）、把 accept 变成 no-op（:1364）⇒ 贡献方会在之后的请求里重发自己未被接受的状态。触发条件是合并后的载荷序列化失败（:1353-1366）。HTTP 错误路径是另一条、且不去字段：非 2xx 时适配器解析响应体、先给 files.retry(detail) 一次机会，否则直接抛错（:2200-2213）—— 而那个重试只在"有文件在用、且提供方的错误被判为陈旧 id"时返回 true，且每个请求只允许一次（:1305-1315）。⇒ "去掉辅助字段重发同一个请求"会是在一条已存在的路径上做延伸，而不是新增机器 —— 这与提案自己那句"这一项是三件里改动最小的"是一致的。

断路器 / 持久标记 / 面向用户的提示：都没有。 两个包里都没有断路器或"被阻挡"状态的表述；字段被去掉时留下的唯一痕迹，是序列化失败路径上的一条 logger.warn（:2252-2253）。没有会话级状态、没有持久化、没有面向用户的信号。

补一句分类那条的现状：把 400 与 413 映到 INVALID_REQUEST 的那个分支，在 rc.1 与 rc.2 里完全一致（:1748-1749）。

3. 发布级 diff 必须以已发布 artifact 为对象

第三条护栏举的例子是：release notes 说不出"这次升级会开始上传你的整份会话历史"。树是可以读的，但答案不在树里。@deepseek-ai/dsh-subagent 已发布集合里有一个实例：

• 最后一个带 2 的已发布 artifact：0.1.1-rc.2 —— 2026-08-21T12:32:59Z。
• f76a225a7d 合并，descriptor 常量在 master 上变 3 —— 2026-08-24。
• 首个带 3 的已发布 artifact：0.1.2-alpha.2 —— 2026-08-30T14:02:58Z。
• 这两个 artifact 之间的发布：没有。

在这两个日期之间，master 与最新可安装 artifact 不一致（3 对 2），⇒ 按 merge 日期取 diff，会把一项变化报成"已生效"，最多比任何用户能拿到它早六天。"哪个版本最先包含 X"是同一个问题：只有逐版本扫已发布产物能回答，因为树无法表达哪些版本可被安装到。而"默认安装会解析到哪个版本"是树 diff 根本看不到的第二个输入。

边界：以上读于 2026-09-25，取自已发布 tarball 与登记处元数据，未执行任何代码。第三条护栏里的 CI fixture 与 wire invariant 两部分，从仓库外不可核实。prior-art 表里的各条线索我没有逐条打开。行号取自上面点名的 rc.2 tarball；常量沿革取自 npm 上 @deepseek-ai/dsh-subagent 的已发布版本清单。

声明：上列读数由我本人针对已发布 npm 产物 tarball 与登记处元数据完成；文稿撰写由 AI 辅助；核验与发布由我本人负责。我没有工程背景 —— 若任何技术表述有误，请直接指出，我会对照工具链重新核实并更正。我们是插件作者、不是维护者，本文不陈述任何官方政策。

本报告由 OfferKuai（Offer快）团队提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/ | 联系：contact@offerkuai.com