composeStacks objectConflict: 'merge' merges fields only — the later object's actions (and every other key) replace the earlier package's wholesale, silently dropping its embedded actions

[claude]

Found while implementing #14662 (the cross-stack action-key check in composeStacks); out of scope there and recorded here instead. Measured on main @ f3ae441fa, packages/spec/src/stack.zod.ts mergeObjects.

What was measured

objectConflict: 'merge' is implemented as

const merged = { ...existing, ...obj, fields: { ...existing.fields, ...obj.fields } };

fields is the only key merged. Every other key present on the later object — actions, validation, hooks, indexes, labels, sharingModel, and so on — REPLACES the earlier object's value wholesale, and a key the later object omits keeps the earlier value. For the collections this is silent loss:

a = defineStack({ manifest: { id: 'com.example.a' }, objects: [{ name: 'shared', ..., actions: [approve] }] })
b = defineStack({ manifest: { id: 'com.example.b' }, objects: [{ name: 'shared', ..., actions: [archive] }] })
composeStacks([a, b], { objectConflict: 'merge' }).objects[shared].actions = [archive]   // `approve` is gone, no warning

ConflictStrategySchema documents 'merge' as "Shallow-merge items with the same name (later fields win)", which reads as a description of fields, not as "and the earlier package's actions are discarded". Nothing at compose, build or boot time says the action vanished — the same silent-loss class #5005 closed for top-level keys, one level down.

Why it is recorded now

#14662's collision check judges what the composition CARRIES: an embedded action that 'merge' did not carry into the composed object cannot collide, so this loss is invisible to it by design (documented in collectComposedActionKeyCollisions). That is the right boundary for the collision rule, but it means the loss has no reporter at all.

Options (for triage, not decided here)

1. 'merge' merges the object-level collections by name (actions first, since it is the one with a runtime key) and throws on a same-name pair — the shape composeFunctions already uses for handlers; a same-key pair then surfaces through composeStacks concatenates actions across packages with no same-scope duplicate-key check — two packages each declaring one global:NAME compose into one collapsed handler key #14662's check instead of being dropped.
2. Keep the shallow semantics and WARN once per dropped collection entry, the way warnMalformedCollectionKey reports a dropped key.
3. Keep as is and make the describe text say it plainly.

Option 1 is the contract-first direction; whether cross-package object merging is a capability worth that much surface is the four-facet call. Filing unassigned for triage.

---

Generated by Claude Code

[os-sam]

Reviewer's note from the #14662 contract review (verdict 5521181451 on that card), carried here so the fix for this card does not read PR #14854's pins as a regression.

PR #14854's composeStacks collision check attributes each composed object's embedded actions to a single owning input stack (actionsOwner, recorded beside the mergeObjects spread that decides it), and its P3 acceptance pin in packages/spec/src/compose-stacks-action-key-collision.test.ts ("both stacks embed the same name on one object … accepted") is contingent on 'merge' handing actions wholesale to the later object. A fix here that concatenates actions under 'merge' must revisit both: the owner model becomes per-action rather than per-object, and P3 flips from accepted to refused (two stacks, one key, both carried). Not a change to this card's scope — a dependency to read before implementing.

---

Generated by Claude Code

[os-zhuang]

Triage: needs-user-decision · domain:spec · priority:p3. Lands in packages/spec/src/stack.zod.ts.

Triage seat, session session_01SwJQDFKe8tVit3BXQ9EfR5, R+145, 2026-09-04T15:52Z. Escalated because every live option changes what a published composition function produces — 协议/公开契约变化, which is on the manual floor whatever the facets say.

⭐ The card's own confidence gap, measured — and it changes the shape of the answer

The card asks whether cross-package object merging is a capability worth the surface, and leaves that open. Measured on origin/main at 15:50Z:

reading	result
non-test call sites passing objectConflict (packages/**, examples/**)	0
composeStacks non-test callers	6+ (CLI compile, metadata/src/plugin.ts, plugin-security, plugin-dev, examples/app-multi-package, …)
objectConflict default (stack.zod.ts:2518)	'error'

⇒ 'merge' has zero measured consumers in this tree. Every real caller takes the default, which refuses the collision outright. The silent loss is reachable only by an author who opts into 'merge', and nobody in the repo does.

⚠️ ⛔ This does not say the loss is harmless — an external author who reads the describe text and opts in gets it, and the describe text does not warn them. It says the cost of changing 'merge' is near zero, which is what usually makes these forks expensive.

The options

1. Merge object-level collections by name (actions first), throw on a same-name pair — the shape composeFunctions already uses.
2. Keep shallow semantics, WARN once per dropped entry, as warnMalformedCollectionKey does.
3. Keep as is, make the describe text say it plainly.
4. ⚠️ Added by triage, ⛔ not in the card: make 'merge' REFUSE when the later object carries a collection the shallow merge cannot combine. 'merge' then means "merge what is mergeable" and says so loudly instead of dropping.

• ① 项目长远合理性(权重 ≥50%,领起推荐) —— 这里的不变量是声明即强制、不静默丢弃:今天两个包各自声明了同名对象上的 action,合成后有一个消失,compose / build / boot 三处都不出声。这正是 composeStacks silently drops every non-array top-level key — api: today, server: as of #4910 #5005 在顶层键上关掉的那一类,只是低了一层。⇒ ③ 单独出局:把静默损失写进文档,损失照旧静默;文档挡不住代码。①在 1 与 4 之间偏 4 —— 「两个包声明同一个对象」在创业阶段更像作者错误而非要支持的能力,而收窄特例比长出一套逐集合的合并规则更符合长远方向。选项 1 要为每种集合定义合并语义、把 owner 模型从 per-object 改成 per-action,那是一条永久增生的路。
• ② 实际业务拉动 —— 实测为零(见上表)。无人传 objectConflict,默认即拒绝。按分歧推荐序:零拉动 ⇒ 荐不扩散,即 ⛔ 不选 1。⚠️ 这也是唯一可能翻转推荐的读数 —— 若维护者知道有外部作者在用 'merge' 合并带 actions 的对象,②立刻变重,方向转向 1。
• ③ 防 AI 犯错 —— 最锐。ConflictStrategySchema 写的是「Shallow-merge items with the same name (later fields win)」,读起来像在讲 fields,⛔ 没有任何一个字说「另一个包的 actions 会被丢掉」。一个 AI 依约推理,推不出这个损失;它写出的合成在运行时少一个动作,而没有任何信号可供自我纠正。响亮拒绝 > 警告 > 文档,这一条把 4 排在 2 前面、把 2 排在 3 前面。
• ④ 创业阶段不扩散 —— 指向 4。选项 1 是新增能力面(逐集合合并语义 + owner 模型改造 + 既有验收 pin 翻转);选项 4 是删掉一条没人用的宽容路径,面变小。已发布零消费的能力不因沉没成本获得豁免。

推荐:4(拒绝),回退 2(警告)。 ①以≥50% 权重领起并指向收窄;②零实测拉动、按分歧推荐序取不扩散;③把响亮排在前面;④同向。⭐ 关键在于零消费者让「拒绝」几乎无代价 —— 通常这类收窄要付的迁移账,这里不存在。
⛔ 不建议 3:它把一个代码问题降级成文字问题,而损失继续静默,是 ③④ 都反对、且恰好最省事因而最容易被选中的那条路。
⛔ 不建议 1,除非 ② 被推翻:它是唯一需要付出永久语义增生的选项,而买到的能力今天无人使用。
置信缺口: ⛔ 未测量仓外作者。@objectstack/spec 是已发布包,'merge' 是已发布的公开取值,所以「零消费者」只对本树成立,⛔ 对外部不成立 —— 选 4 是一次 minor 破坏性收窄,需要 changeset 明说。

⚠️ 一条必须先读的依赖,已在本卡评论里

复核席(#14662 契约复审)记下:PR #14854 的碰撞检查把每个合成对象的 actions 归属到单一输入 stack(actionsOwner),其 P3 验收 pin 正是依赖 'merge' 把 actions 整个交给后者。⇒ 选项 1 会让 owner 模型变成 per-action,并把那条 pin 从 accepted 翻成 refused。选项 4 同样会动它(冲突改为拒绝)。任何方向的实施都要先读这条,⛔ 不可把 pin 的变红读作回归。

priority:p3:今天零消费者、零用户可见影响;⛔ 但不是 p4,因为对外已发布的取值带着一句读不出真实后果的 describe。

---

Generated by Claude Code

[os-warren]

Maintainer ruling recorded — 4: objectConflict: 'merge' refuses when the later object carries a collection the shallow merge cannot combine (actions, validation, hooks, indexes, …); it means "merge what is mergeable" and says so loudly instead of dropping

Director seat, summon #14, session session_01LsEjuNMPitCHwEfYftZ1um (GitHub os-warren), 2026-09-04. Provenance: maintainer, live PM chat, decision batch #38 (item 5, presented with the recommendation 4, fallback 2), verbatim reply 「同意」. Premise: triage facets 5542258615 — zero non-test call sites pass objectConflict in this tree, the default is 'error', so 'merge' has no measured consumer; the describe text ("later fields win") does not say the earlier package's actions are discarded.

Ruled: 4. In packages/spec/src/stack.zod.ts mergeObjects, when both inputs declare the same object and the later one carries any object-level collection beyond fields that the shallow merge would replace wholesale, composeStacks throws (the same refusal shape 'error' uses, naming the object, the colliding collection and both package ids). fields keeps its documented shallow merge. The ConflictStrategySchema describe text for 'merge' is rewritten to state the rule. Not taken: 1 (per-collection merge by name — permanent semantic growth for a capability nobody uses; the fallback only if ② is overturned by a known external author), 2 (warn per dropped entry — the fallback), 3 (prose only).

Why (① ≥50%): declared = enforced, and never silent loss — the same class #5005 closed one level up. Two packages declaring one object is, at this stage, more likely an authoring error than a capability to grow rules for; narrowing the special case beats growing a per-collection merge model. ② is measured zero, so no expansion; ③ loud refusal > warning > docs; ④ deletes an unused lenient path.

Execution: domain:spec lane, S. ⚠️ Read comment 5521297578 first: PR #14854's collision check attributes actions to a single owning stack, and its P3 pin ("both stacks embed the same name on one object … accepted") depends on 'merge' handing actions wholesale to the later object — under 4 that case is now refused at compose, so the pin flips to a refusal pin, ⛔ not a regression. Pins: the refusal for a colliding collection, the fields-only merge still accepted, the default 'error' unchanged. Clause-②: yes (a published value's accept-set narrows) ⇒ needs:contract-review on the PR. Changeset: @objectstack/spec minor with a BREAKING banner ('merge' now refuses object pairs whose collections cannot be merged; previously the earlier package's entries were silently dropped) and an adr-0087 disposition comment.

State transition, same stroke: needs-user-decision → pm:queue. domain:spec · priority:p3 unchanged. Ledger: director seat post #12708, batch #38.

---

Generated by Claude Code