ADR-0130:composeStacks 增加 preserve(保留 N 份 manifest)模式,默认 'last' 不变

[os-sam]

Blocked-by: #14161

实现 ADR-0130 Consequences 表第 3 行(#14122 §5.3)。依赖 #14161 的 packages[] schema。

要求

1. composeStacks 的 manifest 选项(packages/spec/src/stack.zod.ts:1759,现为 'first' | 'last' | index,刻意的挑选语义)新增保留模式:N 份 manifest 全部进产物的 packages[],子包身份不丢。
2. 默认值 'last' 不变——现有调用方零感知(One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 §6.2)。
3. 保留模式的输出与 ADR-0130 D4:产物 schema 增加可选 packages[] 列表,两种形态都读,分段加载键位结构性预留 #14161 的 schema 对齐(packages[] 元素恒为对象)。

Clause-②

packages/spec/src/** 命中路径肢;新增选项值 = 公共面扩宽 ⇒ 预期 yes,挂 needs:contract-review,PR 恒 draft 待复审。

验收

既有 'first'/'last'/index 行为逐位不变(pin);保留模式下 N 包身份(id/namespace/依赖声明)完整可读;换档 minor。

[hotlong]

认领 / claiming this card.

• session: session_01UHvF5hyiZjnCyExFnfQB8m
• branch: claude/issue-14164-composestacks-preserve
• epic: One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 · ADR: ADR-0130 Consequences 表第 3 行

阻塞已解除：#14161 的 packages[] schema 已于 2026-09-01T13:23:32Z 随 PR #14191 落地 main（e6212915），保留模式有了对齐的输出形状，本卡可以开工。

派发前复读过本卡评论区：无在先认领。与 #14162 并行，互不依赖。

⚠️ 承接卡面约束：默认值 'last' 不变，现有调用方零感知；保留模式的输出元素恒为 { manifest: … } 包装对象，与 #14161 落地的 ArtifactPackageEntrySchema 同一个 schema，⛔ 不另行推导包装形状。#14191 已在 stack-artifact-packages.test.ts 留了一条 pin 钉住今日的挑选语义（leaves the singular manifest pick-one semantics alone），本卡改动它时应当是可见的改动而非静默失效——那条 pin 就是为此留的。

---

Generated by Claude Code

[hotlong]

os-dev-report

{
 "issue": 14164,
 "status": "done",
 "branch": "claude/issue-14164-composestacks-preserve",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/14223",
 "premise_still_valid": true,
 "summary": "composeStacks' `manifest` option gains a fourth value, 'preserve': every input's package identity is folded into the composed artifact's `packages` list (ADR-0130 D4) instead of N-1 being discarded. Which entries a stack contributes is D4's read-both rule applied to the inputs (declares `packages` -> those entries; no `packages` -> its singular `manifest` as a single-element list), so a stack carrying both contributes once and no de-duplication pass exists. Entries reuse ArtifactPackageEntrySchema from #14191 - the wrapper shape is not re-derived. The default stays 'last' and preserve is additive over it: the singular `manifest` is still selected by the same rule, so preserve's output is the default's output plus the package list, and no consumer reading composed.manifest loses a key. `packages`' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and is pinned as an equality with preserve where every stack carries `packages`. The pin #14191 left on purpose was retitled '... BY DEFAULT' with its assertions unchanged - which is itself the finding, since the default path is exactly what this card did not touch - and not deleted. HALF-STATE NOTE for PM: the card's assignee field read EMPTY at pickup (claim comment present and matching this session, labels present); proceeded per dispatch. One judgement call is flagged in the PR body for the contract reviewer: preserve retains the singular `manifest` rather than clearing it; ADR-0130 pins neither way.",
 "tests": "All runs at final commit a47ef393, clean tree. (1) Package suite: `pnpm --filter @objectstack/spec exec vitest run` -> exit 0, 'Test Files 450 passed (450) / Tests 12068 passed (12068)'. (2) `pnpm --filter @objectstack/spec run typecheck` -> exit 0 (tsc --noEmit + check:scripts-typecheck + check:test-typecheck, so the new test file is type-checked, not merely present). (3) ABLATION, red->green: mutated `if (opts.manifest === 'preserve') {` to `if (false) {` in packages/spec/src/stack.zod.ts. No rebuild is involved and that is proven, not assumed - the pins import './stack.zod' relatively, so vitest resolves package SOURCE, and the mutation turning them red is itself the proof it reached what the test resolves. Mutation confirmed ON DISK before any result was read, anchored on the changed text rather than on the editor's exit code: injected-count 1, removed-count 0, blob b540201d -> 7bf25448. Mutated leg: 'Tests 7 failed | 71 passed (78)', the 7 being every preserve pin; the 'first'/'last'/index pins stayed GREEN, the correct direction since they must be unaffected. Restore leg proven BY BYTES: `git checkout HEAD -- ABSPATH` (pinned to HEAD, not the bare form that reads the polluted index; absolute path from `git rev-parse --show-toplevel`; script carried a trap on EXIT INT TERM), working blob back to b540201d = HEAD blob, `git diff HEAD` empty, then 'Tests 78 passed (78)'. The FIRST ablation pass measured only 5 red and that caught two vacuously-green pins of my own (a `for` over an absent list iterates zero times; 'output is default plus list' holds trivially when nothing is added) - both fixed to assert the addition first, in commit a47ef393, before the second pass measured 7. (4) GATES, derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` = 52 commands, each exit code captured BEFORE any pipe: 47 exit 0. The 5 non-zero are all PREREQUISITE NOT MET / NOT MEASURED, none a finding - check-dev-prereqs (exit 1), check:dual-build-cjs-loads (3), check:type-check-debt (3), check:doc-formula-expressions (3) all want the WHOLE workspace built (66 of 67 packages have no dist/), and check-test-completeness (3) / check-half-states (3) exit by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally, after which check:api-surface went exit 1 -> exit 0 on real declarations. CI owns the repo-scale remainder. (5) LINT as a DECLARED NARROWING, all three evidence pieces: population read from eslint's own config (`--print-config` resolves for each changed file, exit 0), count read from `--format json` (3 files linted, 0 errors, 0 warnings), and invariance because this repo runs one eslint.config.mjs that never enables type-aware linting for ANY file (no parserOptions.project, no typed rules - stated and measured at eslint.config.mjs:328), so this diff cannot move the verdict on any untouched file.",
 "mcp_calls": "7 - issue and PR reads went through the zero-quota public-repo payload channel after a repo-scoped REST probe returned 403 for this seat; MCP was used only for the writes (create PR, body repair, label union) and the reads those writes had to be verified by.",
 "open_questions": [],
 "out_of_scope_findings": [
 "NOT FILED, handed to PM for triage with the reason: skills/objectstack-platform/SKILL.md:507 teaches composeStacks' options with `manifest: 'last'` and now omits 'preserve'. Deliberately not filed as a card, on two grounds: (a) the doc is not WRONG - the default is unchanged and the snippet stays accurate; (b) teaching the mode in a customer-published skill before ADR-0130 D5's load path lands would document a mode that folds identities nothing downstream iterates yet, so the natural home is the D5 card, not now. Touching skills/** is also budget-governed and this dispatch carried no net-increase budget. PM's call.",
 "PLATFORM OBSERVATION, no card: the PR body's angle-bracket fragment in the restore-leg sentence was eaten by the GitHub sanitizer on create; caught by the mandated full read-back and repaired with a placeholder spelling. Also measured: the create call appended a SECOND session-URL footer of its own, and the PR already carried an auto-applied `size/l` at first read - so the label write went out as a union, and the compare-read-back confirms ['size/l','needs:contract-review'] with nothing stripped."
 ]
}

Generated by Claude Code

---

Generated by Claude Code