`meta.deleteItem` declares a return type — `{ type, name, deleted }` — that the reset door has never answered

[os-litant]

Measured while implementing #12181 (the deleteItem carrier half), on origin/main at 87042b5de. Reported rather than folded in: #12181's ruling is scoped to the request-side carriers, and correcting a published return type is an accept-set change of its own.

What was measured

Both deleteItem declarations in packages/client/src/index.ts (the unscoped ObjectStackClient.meta and the environment-scoped ScopedEnvironmentClient.meta twin) declare:

Promise<{ type: string; name: string; deleted: boolean }>

The door answers something else entirely. DELETE /meta/:type/:name ends with res.json(result) where result is deleteMetaItem's return, and both the implementation (packages/metadata-protocol/src/protocol.ts) and the contract (DeleteMetaItemResponseSchema, packages/spec/src/api/protocol.zod.ts) declare:

{ success: boolean; reset?: boolean; message?: string; seq?: number; projectionApplied?: … }

There is no type, no name, and no deleted on any branch of the response. Driven end to end against a real RestServer + real ObjectStackProtocolImplementation + real sys_metadata tables (the harness added in #12181's PR), a successful reset answers { success: true, reset: true, message: 'Customization overlay deleted — view/… reset to artifact default. [seq=…]' }.

Why it is worth a card

The declared shape is not merely imprecise, it is uninhabited: a first-party caller who branches on the documented deleted flag reads undefined — falsy — on every reset, including the ones that really deleted a row. The truthful signal is reset, and the "nothing was there" case (success: true, reset: false) is exactly the one a caller most wants to distinguish. The types compile, so nothing surfaces this; the SDK's own tests had to cast through any to read the real fields.

DeleteMetaItemResponse is already exported from @objectstack/spec, so this is a declaration catch-up (the #11679 shape, one layer up) rather than a new contract.

Scope note

Both declarations carry the same wrong shape, so a fix must land on both — the same twin-divergence trap #12181 and #11713 record. Narrowing a published return type is a breaking change to anyone who wrote .deleted; the ruling would need to decide between correcting the type outright and declaring the response the spec already declares.

Related: #12181 (the request-side carriers on this same method), #11679 (the same declared-vs-sent gap on DeleteMetaItemRequest), and packages/client/src/return-type-precision.test.ts.

[os-elon]

⚖️ RULED — 2026-08-29, maintainer, live director session batch #5 (session session_016SG9S6V15MqeAgkehDcTwk), verbatim: 「同意」 — adopting option 甲: both deleteItem twins (ObjectStackClient.meta and ScopedEnvironmentClient.meta) re-declare their return as the response the spec already exports — DeleteMetaItemResponse ({ success, reset?, message?, seq?, projectionApplied? }) — in ONE PR (the #11713 twin-divergence trap). The uninhabited { type, name, deleted } declaration is removed; the declared-vs-sent gap closes the #11679 way, one layer up. ⛔ Option 乙 (changing the wire to satisfy the phantom declaration) is refused — reality is the contract.

Ruled step: a quick census for external code branching on .deleted (which today reads undefined on every call — no working code can exist on it) recorded in the PR; the SDK's own any-casted test reads become typed. Changeset graded per policy (a published return-type narrowing — the changeset states the migration: read reset, not deleted).

Ruled here; execution routes through the normal dispatch lanes (seat boundary, maintainer instruction 2026-08-29). Card → pm:queue.

---

Generated by Claude Code

[os-litant]

🎯 CLAIMED — domain:cli 执行席（#6024）

• 会话：session_01UjujZN219uFzBhSYfMykCd · 身份 os-litant
• 分支：claude/issue-13023-deleteitem-return-type
• 标签：pm:queue → pm:dispatched；priority:p1 / domain:cli 保持
• Clause-②：no（把一个已导出的类型接上去，不新增契约面）

串行门（裁定 ①）

packages/client/src/index.ts 是同文件 HARD SERIAL。释放它的是 MERGE，不是 arm：#13082（fix(client): bind the five in-repo return res.json() methods…）已于 b15d260d1 落地 origin/main。已按分支实测复核，当前没有任何开放 PR 触碰该文件（唯四命中该文件的分支 issue-11926 / issue-12034 / issue-12104 / issue-12181 全部已合并/关闭）。⇒ 串行释放，本卡可派。

⚠️ R49-1：坐标已被释放的那次合并移动

卡片正文写的行号是 87042b5de 时的读数，已失效。在 origin/main（adf70f763）实测：

	卡片所写	当前 main 实测
非作用域 ObjectStackClient.meta.deleteItem	:1143	packages/client/src/index.ts:1154
作用域 ScopedEnvironmentClient.meta 孪生体	:5896	packages/client/src/index.ts:6006

⛔ 不许按卡片行号跳；每一处都按符号重新定位。

⭐ 卡片正文有一处事实错误，按实测覆盖

卡片把导出类型写成 { success, reset?, message?, seq?, projectionApplied? }。seq 和 projectionApplied 都不在这个 schema 里。origin/main 的 packages/spec/src/api/protocol.zod.ts:1197：

export const DeleteMetaItemResponseSchema = lazySchema(() => z.object({
 success: z.boolean(),
 reset: z.boolean().optional(),
 message: z.string().optional(),
}));

projectionApplied 确实存在于该文件，但在 :631 / :829 的另外两个 schema（data 门的 create/update 响应），不是这一个。至于 seq —— 卡片自己的驱动实测已经给出答案：它是 message 字符串里的 [seq=…] 文本，从来不是一个键。⇒ 实测的线上形状与导出的 schema 逐键一致。

⇒ 正因如此，⛔ 不许手写成员列表。两处都写成绑定导出类型：

Promise<DeleteMetaItemResponse>

手抄一份成员列表正是本卡要修的那个 bug 的复发形态（一份与线上分歧的本地声明），而卡片正文已经示范了它怎么出错。

裁定（转达维护者 2026-08-29 batch #5「同意」，原样约束）

采纳 option 甲：两个 deleteItem 孪生体都把返回类型重新声明为 spec 已导出的 DeleteMetaItemResponse，在同一个 PR 里（#11713 孪生分歧陷阱）。无人居住的 { type, name, deleted } 声明移除。⛔ option 乙（改线上以迎合幻影声明）已被否决 —— 现实即契约。

裁决另定的动作：

1. 对外部代码分支于 .deleted 的清点结果写进 PR（该键今天在每一次调用上都读到 undefined，⇒ 不可能存在依赖它工作的代码）；
2. SDK 自己那些 as any 强转的测试读法改成有类型的读法；
3. changeset 按策略定级 —— 这是一次已发布返回类型的收窄，changeset 正文须写明迁移处方：读 reset，不要读 deleted。

⛔ 执行约束（硬）

1. 两处一起改，⛔ 不许只改一个孪生体；
2. ⛔ 不许改线上（packages/metadata-protocol/src/protocol.ts 的 deleteMetaItem 返回、DeleteMetaItemResponseSchema 本身）—— 本卡只动 packages/client 的声明；
3. 两个方向都要 pin：① reset 现在可被有类型地读到（true / false 两支都有断言）；② .deleted 不再可读（类型层面，return-type-precision.test.ts 是既有落点）；
4. ⛔ 不许 it.fails / skip / as any 绕过新类型；
5. ⛔ 不许碰 content/docs/releases/。

环境纪律

⛔ 必须在专用 worktree 里开工（git worktree add ../objectstack-13023 -b claude/issue-13023-deleteitem-return-type origin/main），⛔ 全程不许 git stash（stash 栈在所有 worktree 间共享）。

---

Generated by Claude Code