spec: 按 ADR-0049 摘除 `IStorageService.list(prefix)` 契约成员(零消费方,双适配器语义分叉 —— #5266 方案 2,维护者已批)

[os-zhuang]

Part of #5266(父单存档了完整分析与维护者裁决)。

任务

从 packages/spec/src/contracts/storage-service.ts 摘除 IStorageService.list(prefix) 可选成员,按 ADR-0049 enforce-or-remove 与 spec 退役流程执行(退役 pin、api-surface 基线、必要的 ADR-0087 登记 —— 以 spec-property-retirement playbook 与 spec 车道现行纪律为准;服务契约成员与 authorable property 的流程差异由实施者按现状判断)。

依据(实测,见 #5266)

• 今日零消费方:仓内唯一调用点是 SwappableStorageService.list 透传,REST / CLI / routes 均不调;
• 两个自带适配器语义分叉且双双静默给不完整答案(local:单层 + 目录当文件;S3:递归 + 1000 条截断无信号);
• 维护者 2026-08-05 批准摘除(创业聚焦:无拉动声明面从紧;先例 主题引擎发出的 9 组 CSS 变量零消费方(--font-size-* / --z-* / --duration-* …):ADR-0049 该判去留 #5021/ui/ 五个交互配置文件(22 个 z.object 站点)没有任何承载键:实测「无授权门」,按 ADR-0049 定去留 #4988/ADR-0049:plugin-runtime.zod.ts 剩余家族(DynamicLoadRequest / DynamicUnloadRequest / DynamicPluginResult / PluginSource / DynamicPluginOperation)四仓零 runtime consumer —— enforce-or-remove 悬置待裁 #4834);未来真需枚举时按带游标形状(list(prefix, {cursor, limit}))重新设计,不继承坏签名。

下游

packages/services/service-storage 的实现摘除在兄弟单(services 车道,Blocked-by 本单)。TS 层面:契约成员摘除后适配器上的多余方法不破坏类型,故本单可独立先行。

归 spec 座位(domain:spec),经 backlog sweep 认领。

[qq9340100]

认领:PM 循环第 1 轮(spec 车道,batch 扩到 5 后补位)
会话:session_011M7UwH25Unfi73UHim7ajY(账号 qq9340100)
分支:claude/issue-5540-retire-istorageservice-list
Worktree:objectstack-issue-5540
域:domain:spec
文件面:packages/spec/src/contracts/storage-service.ts(摘除 list(prefix) 契约成员)、退役 pin 测试、api-surface 等生成物基线重生成、按 spec-property-retirement playbook 判断是否需 ADR-0087 登记(服务契约成员 vs authorable property 的流程差异由 dev 按现状判断并在 PR 说明)、.changeset/*.md。⛔ 不碰 packages/services/service-storage 实现(兄弟单归 services 车道,Blocked-by 本单)。(越界即停,报告说明)

在飞互斥说明:本轮同批 #5858(contracts/sharing-service.ts)、#5744(scripts/build-openapi.ts)、#5832(shared/http.zod.ts + scripts/build-schemas.ts)、#5899(data/hook.zod.ts),源文件与本单互不相交;生成物基线家族相交,落地由 PM 串行接力。

---

Generated by Claude Code

[qq9340100]

实施进展 + 一处拆单前提被证伪,需要 PM/维护者拍板(会话 session_011M7UwH25Unfi73UHim7ajY,分支 claude/issue-5540-retire-istorageservice-list,草稿 PR #5983)。

spec 面已做完且自身全绿:契约成员摘除、两条 @ts-expect-error 退役 pin(sabotage 验证过:放回成员 → check:test-typecheck 精确 ratchet 由 1 涨到 3)、ADR-0087 D3 semantic 登记 storage-service-list-retired(照 IDataDriver.findStream #4484 先例 —— 纯 TS 契约、无人 .parse(),故无 tombstone、无 D2 转换)、生成物整体重生成(check:generated 10/10)、changeset(spec: major)、两页手写文档。pnpm --filter @objectstack/spec test 323 files / 8268 tests 全过,ESLint job 绿。

被证伪的是本单正文那句「TS 层面…故本单可独立先行」。 前半句(适配器类上多余方法不破坏类型)成立;但 SwappableStorageService 是代理,按 IStorageService 类型读 this.inner.list,那是调用方:

src/swappable-storage-service.ts(75,27): error TS2339: Property 'list' does not exist on type 'IStorageService'.
src/swappable-storage-service.ts(78,23): error TS2339: Property 'list' does not exist on type 'IStorageService'.

而且这会让 CI 红 —— 不经由 typecheck script(该包确无此 script),而是经由 tsup 的 DTS 生成步骤(它跑 tsc),TypeScript Type Check job 先 pnpm build 就炸在 @objectstack/service-storage#build。PR #5983 的该 job 实测 failure。

顺序箭头是反的:list?() 在契约上是 optional,所以先删代理透传(services 面)是绿的;先摘契约成员反而不可行。即 #5541 应先行,或与本单合并为一个 PR。最小修复已实测(改完即还原、未提交):删掉 SwappableStorageService.list() 那 6 行 → DTS Build success。

请在两个方案里选一个,我按认领的文件面纪律没有擅自改 packages/services/service-storage:

• A(我倾向):把那 6 行 + 2 处测试并入本 PR,一次原子落地,main 任何一刻都不红;service-storage: 摘除 Local/S3 适配器与 SwappableStorageService 的 list 实现及测试(#5266 方案 2 的实现半,随 spec 契约摘除) #5541 缩为「双适配器实现摘除」。
• B:先出 services 面小 PR 删透传(绿),本 PR 随后转绿;service-storage: IStorageService.list(prefix) means two different things on the two shipped adapters (local: one level, directories as files; S3: recursive, silently capped at 1000) #5266 的 Blocked-by 反过来写。

---

Generated by Claude Code