fix(spec): composeStacks carries each bound standalone action once in the composed object

[claude]

Fixes #14847

Summary

defineStack ends with mergeActionsIntoObjects: every standalone action carrying objectName is copied into that object's actions on the way out, and the standalone stays in stack.actions. composeStacks concatenates its inputs' actions and ended with the same merge — so each bound action was appended to its object a SECOND time, beside the copy the input's own build had put there.

mergeActionsIntoObjects is now idempotent over its own output: a bound action the object already carries by identity is not appended again. Identity against the standalone list, deliberately not equality — the only way an entry of stack.actions is the very same object as an entry of object.actions is that a previous merge put it there. Nothing else in the merge moves: order, the order sort, the untouched-object fast path.

Measured on main @ 6392b9c2 (BASE), defineStack outputs as inputs — before / after

case	before	after
two stacks, default	a_item.actions = [dup_x/BOUND, dup_x/BOUND]	[dup_x/BOUND]
… manifest: 'preserve'	same doubling on objects; packages[].manifest.objects carried ONE each (the two halves disagreed)	[dup_x/BOUND], both halves agree
three stacks each embedding embN and binding bN to one object, override / merge	shared.actions = [emb3/EMB, b3/BOUND, b1/BOUND, b2/BOUND, b3/BOUND]	[emb3/EMB, b3/BOUND, b1/BOUND, b2/BOUND] — the surviving stack's declared actions plus each concatenated standalone once
defineStack(composeStacks([a, b]))	REFUSED — 'a_item:dup_x' is declared 3 times	REFUSED — is declared twice, the identical line defineStack(a) gets for a lone built input
defineStack(a) (a lone built input)	REFUSED — declared twice (the landed #14686 pin at stack-duplicate-action-key.test.ts:236)	unchanged
hand-written twin, strict	REFUSED by #14686's rule ('t_item:tw' is declared twice)	unchanged
a marker key on a standalone action, strict	REFUSED — actions.0: Unrecognized key(s) on this action: \__echo``	unchanged (why identity, not marking)
strict: false, ONE action object in both positions	carried twice	carried once — one declaration, in the mode that opts out of #14686's walk by choice
examples/app-multi-package composed object (the object compile.ts:318 parses), JSON sha256	b1225296475ff3c7… (7351 bytes, both objects carry 0 actions)	byte-identical

The fork, decided by measurement (dispatch ruling)

Both directions can satisfy (a) the pins and (b) the twin refusal — both would key on identity, since a marker does not survive the strict parse. They differ on the published shape and on what they touch:

• Idempotent merge (taken). Output = the previous output minus the duplicate entries; nothing reordered; collectComposedActionKeyCollisions and its message untouched (it runs before the merge). Smallest shape change.
• Compose the authored shape first. Stripping echoes before mergeObjects changes the input of feat(spec): composeStacks refuses two stacks whose actions resolve to one scope-qualified runtime key #14854's walk and therefore its message — the landed pin 'com.example.b' (stack #1) at stack.actions[0] + objects['shared'].actions[0] names the echo site — and stripping after the walk but before the final merge is the same identity skip with a reorder of the surviving stack's own bound action ([emb3, b1, b2, b3] instead of [emb3, b3, b1, b2]). Larger shape change for the same result.

Criterion (c), round-trip through defineStack, holds in the only form the landed rulings allow. defineStack refuses ANY built stack that binds an action — pinned at stack-duplicate-action-key.test.ts:236 ("a built stack fed back in … is refused — author the source shape, not the artifact") — so defineStack(composeStacks([a, b])) cannot parse when an input binds an action under either direction without weakening that rule, which is ⛔. What this change restores is that composition adds no refusal of its own: with no bound action the composed output parses cleanly (as before), and with bound actions it is refused with the same declared twice line a single built input gets, no longer 3 times. Both are pinned. The card's and the triage's "not round-trippable through the door that built its inputs" is therefore a property of every built artifact, not of composition — noted for the contract review, not acted on here.

Rulings honoured

• feat(spec): defineStack refuses two actions that resolve to one scope-qualified runtime key #14686's same-key refusal: untouched, and pinned still firing on a hand-written twin (code path and message).
• feat(spec): composeStacks refuses two stacks whose actions resolve to one scope-qualified runtime key #14854's collectComposedActionKeyCollisions: untouched; its message pins all green (23/23).
• 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 #14848 (objectConflict: 'merge' dropping non-fields keys): out of scope: 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 #14848 remains open and is not touched here; mergeObjects is not edited.
• No equality-based skip anywhere.

Changes

• packages/spec/src/stack.zod.ts — mergeActionsIntoObjects filters the bound list by identity against the object's current actions before appending; TSDoc states the idempotence; composeStacks gains a step-7 comment at its final merge. 31 insertions, 4 deletions.
• packages/spec/src/compose-stacks-action-echo.test.ts — NEW, 12 pins: once under default / preserve / three stacks override / merge; add-on binding to another stack's object; order across the once-merged set; twin refusal; marker refusal; strict: false shared reference; idempotent re-merge by reference; round-trip with and without bound actions.
• packages/spec/src/compose-stacks-action-key-collision.test.ts — only the app-multi-package mirror pin that named composeStacks re-merges bound standalone actions that defineStack already copied into their objects — every bound action appears twice in the composed object's actions #14847 as "the measured shape, not the contract" is tightened to toEqual; no refusal message moves.
• .changeset/compose-stacks-action-echo.md — @objectstack/spec patch.

Verification (all on f1ed87e8, the head; through scripts/pm/os-verify-lock.sh, shared-box seconds)

• pnpm --filter @objectstack/spec build — check-dts-emitted: 34/34, .build-input-hash 6192f26e…; dist carries base.includes(action) (1) and the old append form (0).
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 over the 13 compose-stacks* / stack* / assembled-package-body suites — Test Files 13 passed (13), Tests 339 passed (339).
• pnpm --filter @objectstack/spec typecheck — green, incl. check:test-typecheck: OK — 54 file(s) / 261 error(s) … held; tsc -p tsconfig.test.json --listFiles names the new test file (1 hit), so the test layer verdict covers it.
• pnpm --filter @objectstack/spec check:generated — ✓ All 15 generated artifacts are up to date (check:api-surface, check:docs, check:authorable-surface, check:liveness … all ✓).
• Gate family derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on the actual diff (58 commands): 52 green at exit 0 — incl. check:nul-bytes, check:adr-0087-registration, check:empty-changeset, check:changeset-no-major, check:closing-keyword-parity, check:cross-package-test-inputs, check:test-source-alias, check:engine-double-contract, check:type-check-coverage, and every spec check:* in the list. The script flagged its tree as 4 commits behind origin/main with two gate scripts changed upstream (check-cross-package-test-inputs, engine-double-contract.pinned.json); CI runs the current ones. NOT MEASURED, each by its own verdict text (exit 3 / prerequisite, not a finding): check-dev-prereqs and check:dual-build-cjs-loads and check:type-check-debt (need the whole workspace built — CI owns), check-test-completeness (needs a turbo test log — its usage text says record NOT MEASURED locally), scripts/pm/check-half-states.mjs (live-repo PM sweeper; timed out at 180s with and without --use-env-proxy). check:doc-formula-expressions was re-run after building @objectstack/formula — see the report comment for its line.

Reverse verification (fix committed first)

Mutation: the identity filter removed (const fresh = actionsByObject.get(obj.name) ?? []; — the pre-fix append), proven on disk by anchor counts (injected=1 removed=0) and a differing blob hash (790cfe5c… vs HEAD 8c27145e…). Prediction recorded in the script header before the run: 8 red / 4 green controls in the new suite, 1 red in the collision suite (the tightened mirror pin), 0 red in the #14686 suite. Observed: compose-stacks-action-echo.test.ts (12 tests | 8 failed), compose-stacks-action-key-collision.test.ts (23 tests | 1 failed), stack-duplicate-action-key.test.ts all green — Tests 9 failed | 42 passed (51). No dist leg: these suites import ./stack.zod (relative source), not the package exports, so no rebuild was needed and dist/ stayed on the fix throughout (marker re-checked after restore). Restore by git checkout HEAD -- packages/spec/src/stack.zod.ts under an EXIT/INT/TERM trap with absolute paths, proven by git hash-object equal to the HEAD blob and git diff HEAD --stat EMPTY.

Contract review notes

• Shape change: a composed object's actions is the previous output minus the duplicate entries. Accept set unchanged in both directions.
• One measured consequence outside composition: under strict: false, one action object placed in both positions is now carried once (before: twice). Pinned and documented; flagged here for the reviewer.
• H3 as dispatched ("defineStack(composeStacks([a, b])) parses when no hand-written twin exists") is falsified by the landed feat(spec): defineStack refuses two actions that resolve to one scope-qualified runtime key #14686 pin whenever an input binds an action; the pins assert the achievable form described above.

🤖 Generated with Claude Code

https://claude.ai/code/session_0174WZTU6XcFcS7g2kykC53i

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/getting-started/examples.mdx (via composeStacks (symbol, a top-level function))
• content/docs/getting-started/glossary.mdx (via composeStacks (symbol, a top-level function))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via composeStacks (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json fddfc8db062d61ca68ba482531f5368326109554 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 41a7a209583ca5e4bac713bdb085e54f647ed503 — the merge of head f1ed87e8c84e5fd90836cbf904a44af06684ebf8 into base fddfc8db062d61ca68ba482531f5368326109554, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 41a7a209583ca5e4bac713bdb085e54f647ed503 && git checkout 41a7a209583ca5e4bac713bdb085e54f647ed503
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin fddfc8db062d61ca68ba482531f5368326109554 f1ed87e8c84e5fd90836cbf904a44af06684ebf8 && git checkout -B drift-repro fddfc8db062d61ca68ba482531f5368326109554 && git merge --no-ff f1ed87e8c84e5fd90836cbf904a44af06684ebf8

node scripts/docs-audit/affected-docs.mjs --json fddfc8db062d61ca68ba482531f5368326109554

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs fddfc8db062d61ca68ba482531f5368326109554 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[zhuangjianguo]

Landing provenance (PM seat domain:spec, session_0174WZTU6XcFcS7g2kykC53i, 2026-09-03T18:10Z) — flipping to ready and enabling auto-merge (squash) under the 2026-08-31 clear-is-land ruling.

• Contract review: in-seat at CONTRACT_REVIEW_TIER, PASS · ACCEPT on the card — composeStacks re-merges bound standalone actions that defineStack already copied into their objects — every bound action appears twice in the composed object's actions #14847 comment 5529809100; needs:contract-review cleared on both carriers with compared readbacks in that stroke.
• CI on head f1ed87e8: 50 check runs, 36 success + 14 skipped, 0 red, 0 in progress (18:09Z) — including Lint & Repo Gates and TypeScript Type Check at success.
• Governed-surface test on the changed paths: NOT governed — queue landing applies.
• mergeable_state: clean (18:10Z). Body first line Fixes #14847; no other closing keyword in the body (the other card numbers sit next to no verb).
• Next reading: the added_to_merge_queue timeline event; on MERGED the card closes via Fixes and pm:dispatched is stripped in the same action, then origin/main is probed for the identity-skip in mergeActionsIntoObjects.

---

Generated by Claude Code