Published packages have no removal signal — two public surfaces removed in six days, one still installs clean from npm

[Saidoua]

The repository's stance on pre-stable breakage is deliberate and documented. The naming contract and rename ledger states it plainly: "No alias, compatibility package, duplicate service key, dual event name, or fallback parser remains. The repository rejects the old name." AGENTS.md adds: "Public APIs are pre-stable; update every consumer." As an internal policy this is coherent, and I am not arguing against it.

The question is what "every consumer" means when 251 of the 260 workspace packages publish to npm as public packages. A package on a public registry acquires consumers the monorepo cannot enumerate or update. Two removals in the same week show what that costs today.

The two surfaces

UserQuestionService.registerProvider — a public, documented method: "Register the UI provider. Only one provider may be active in a context," with a DUPLICATE_PROVIDER guard and a disposer. Removed 2026-08-22 by 049170c6d0 (refactor(interaction): move Approval and Question into UI owners), which replaced the single active provider with the Agent-scoped ctx.waterfall. Published in @deepseek-ai/dsh-user-questions@0.1.1-rc.2 on 2026-08-21 12:33 UTC; absent from 0.1.2-alpha.2 onward.

The entire ApiProxy package — @deepseek-ai/dsh-host-apiproxy, eleven published versions from 2026-08-10 to 2026-08-21, publishConfig.access: public. Removed 2026-08-27 by 4f00a8b82a (refactor(api): remove ApiProxy package).

Both replacements are well-designed and properly recorded in Agent Notes — the scoped waterfall in remote event delivery, the transport takeover in session history and event transport. Internally the process worked. Neither carried a deprecation marker in the removed code, and neither note addresses an out-of-repo consumer, because the notes are not written for one.

What an external author sees

Nothing. npm view @deepseek-ai/dsh-host-apiproxy deprecated returns empty — the package still resolves and installs clean, with no indication that it no longer exists upstream. There is no removal ledger to watch, no deprecation flag, and release notes do not distinguish "renamed" from "gone."

The cost is already visible. @wsz987/dsh-channels built its IM question flow on apiProxy in 0.4.2 (2026-08-21), then on registerProvider in 0.5.0 (2026-08-24). Both paths are now orphaned — 0.4.2 by the ApiProxy removal, 0.5.0 by the registerProvider removal. In #5747 the author reported it after a three-layer debug session and attributed it to scoped dispatch, which is not what broke either path. That misattribution is the predictable result of having no removal signal: with nothing to consult, an author reconstructs the cause from whatever changed nearby.

The question

Which of these is intended?

1. These packages are internal implementation detail that happens to be published. Then the fix is upstream of any policy: mark them private, or publish only the packages meant to be built on. Twelve public packages with a stated surface is a very different promise from 251.
2. They are a real extension surface. Then a removal needs a signal an out-of-repo author can receive — npm deprecate on the removed name pointing at the successor is one command per removal, and a removal ledger beside the existing rename ledger would let authors track breakage without reading every merge.

Either answer is workable. What is not workable is that today an author cannot tell which one applies, and finds out by having something break.

---

本仓库对 pre-stable 阶段破坏性变更的立场是有意为之且有文档的。命名契约与重命名台账写得很清楚：「No alias, compatibility package, duplicate service key, dual event name, or fallback parser remains. The repository rejects the old name.」AGENTS.md 另有一句：「Public APIs are pre-stable; update every consumer.」作为内部政策，这是自洽的，我并不反对它。

问题在于：当 260 个 workspace 包中有 251 个以 public 身份发布到 npm 时，「every consumer」指的是谁？公共 registry 上的包会获得 monorepo 无法枚举、也无法代为更新的使用者。同一周内的两次移除，说明了当下的代价。

两个被移除的接口

UserQuestionService.registerProvider —— 一个公开且有文档的方法：「Register the UI provider. Only one provider may be active in a context.」，带 DUPLICATE_PROVIDER 保护和 disposer。2026-08-22 由 049170c6d0（refactor(interaction): move Approval and Question into UI owners）移除，单一 provider 被换成 Agent-scoped ctx.waterfall。它曾发布于 @deepseek-ai/dsh-user-questions@0.1.1-rc.2（2026-08-21 12:33 UTC），自 0.1.2-alpha.2 起消失。

整个 ApiProxy 包 —— @deepseek-ai/dsh-host-apiproxy，2026-08-10 至 08-21 共发布 11 个版本，publishConfig.access: public。2026-08-27 由 4f00a8b82a（refactor(api): remove ApiProxy package）移除。

两者的替代方案都设计良好，且在 Agent Note 中有完整记录——scoped waterfall 见 remote event delivery，传输接管见 session history and event transport。就内部流程而言，一切正常。但被移除的代码里都没有 deprecation 标记，两份笔记也都没有面向仓库外的使用者——因为笔记本来就不是写给他们的。

外部作者看到的是什么

什么也看不到。npm view @deepseek-ai/dsh-host-apiproxy deprecated 返回空——这个包仍可正常解析安装，没有任何迹象表明它在上游已不复存在。没有可供关注的移除台账，没有 deprecation 标记，release notes 也不区分「改名」与「删除」。

代价已经可见。@wsz987/dsh-channels 在 0.4.2（2026-08-21）把 IM 问答流程建在 apiProxy 上，又在 0.5.0（2026-08-24）改建在 registerProvider 上。两条路径如今都成了孤儿——0.4.2 死于 ApiProxy 的移除，0.5.0 死于 registerProvider 的移除。在 #5747 中，作者经过三层调试后提交了报告，并把原因归到 scoped dispatch 上，而那并不是任何一条路径断掉的原因。这种归因错误正是「没有移除信号」的可预期结果：无处可查时，作者只能从附近发生的变更里反推原因。

问题

以下哪一种才是本意？

1. 这些包只是恰好被发布出去的内部实现细节。 那么修法在任何政策之上：把它们标为 private，或只发布真正供人构建的那些包。12 个有明确接口说明的公开包，与 251 个，是完全不同的承诺。
2. 它们确实是扩展面。 那么移除就需要一个仓库外作者能收到的信号——对被移除的包名执行 npm deprecate 并指向后继者，每次移除只是一条命令；在现有重命名台账旁再放一份移除台账，也能让作者不必逐个阅读 merge 就能追踪破坏性变更。

两种答案都可行。不可行的是现状：作者无从判断适用哪一种，只能等东西坏掉才发现。

[argszero]

This is the sixth independent account of the same gap, and the first one to frame it as a policy question rather than a crash report — valuable. The earlier five all arrived as consumer crashes after silent removals between published versions: settingsNamespace removed from dsh-settings (breaking installSettingsSection consumers, tracked through #5363 and again #5599), sessionQuery.observeSession shape drift (#5596), plus the pre-stable contract-drift reports around bundle ids and llm-adapter duck-typing. Every one of them has the same shape you describe: the removed code carried no marker, the Agent Note documents the internal migration only, and the out-of-repo consumer learned about it from a runtime crash they then misattributed (your #5747 example — attributing it to scoped dispatch — is the canonical case).

On your two options, the evidence says these are not accidentally-published internals — they are a real extension surface:

• The platform invites it: dsh plugin add resolves from npm, profiles mount third-party packages against the official family, and the official family publishes 251/260 packages to that same registry. @wsz987/dsh-channels is one of many authors who built twice on two published surfaces; the community plugin ecosystem (the 78-plugin registry scan from [Bug Report] 包族 npm dist-tag `latest` 不一致：全新项目按默认版本安装必然 ERESOLVE（0.0.1-rc.1 的 peer 引用已不存在的包名） #2763) is entirely built on this promise.
• The two removed surfaces you cite are telling in what they have in common: both were single-owner/single-seat designs — "only one provider may be active in a context" with a DUPLICATE_PROVIDER guard, and a whole package owning one transport. The seams that did not break consumers across this same churn are the merge-extensible ones: typed event declaration-merging, effect-disposer registries, per-agent ctx.waterfall. That is a usable heuristic for authors today: single-seat registries and single-owner packages are the most likely to be re-architected; map-extensible seats and disposer-returning registers are the intended extension contract.

So the coherent answer is your option 2, and it does not require weakening the naming contract at all. "No alias, no compatibility package" governs the monorepo's own code; a removal signal is not a compatibility layer. Concretely, three levels, cheapest first:

1. Whole-package/version removal → npm deprecate on the removed name pointing at the successor (one command; npm view … deprecated becomes non-empty; exactly what registerProvider (published-plugin compat seam) is inaudible in scoped waterfalls — legacy providers never see agent-scoped asks #5747's author could not find). This covers the ApiProxy case.
2. In-package export removal (the registerProvider case — npm has no per-export deprecation) → append a removal row to the rename ledger document that already exists; it is already the canonical file authors would watch, and "rename ledger" is one schema extension away from "rename + removal ledger". Even better, make it publish-time: a release gate that diffs each package's exported surface against the previously published version and fails the release unless a ledger entry exists. The repository already runs release gates; the missing input is the shipped-surface diff.
3. Consumer-side → capability guards at registration time (check the method/export before use, fail fast with the ledger entry instead of a mystery TypeError). Not a shim, not a fallback — just a diagnostic that names the removal.

One sibling data point argues the gates should diff shipped tags, not source: #5818 is the same root cause one layer down, where the released-session-format inventory refused two payload shapes that released writers actually emitted (permission/preset origin in 0.1.1-rc.1, flat pi-ai replayState pre-envelope) because the inventory was built from what survives on master rather than what shipped. Package exports and session payloads are different artifacts, but the failure mode is identical: released artifacts validated against master's current shape, with the out-of-repo consumer as the only detector. A release gate that diffs each tagged train's writers/emitters against the frozen inventories would have caught both classes before any consumer did.