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