feat(spec): composeStacks gains manifest: 'preserve' — N package identities survive composition (ADR-0130 row 3)

[hotlong]

Fixes#14164

Implements ADR-0130's Consequences follow-up row 3. composeStacks' manifest option accepts a fourth value, 'preserve': instead of keeping one manifest and discarding the rest, it folds every input's package identity into the composed artifact's packages list (ADR-0130 D4), in stack order.

Why a new value rather than a fix to the old ones

manifest: 'first' | 'last' | index is a deliberate pick-one, and it is correct for the case it was written for — several stacks assembled into ONE published package, which has one identity. ADR-0130 introduces the other case: a release artifact that carries N packages, each keeping its own identity, so a product splits into modules without renaming a single object (the object name IS the table name, the REST path, the formula token and the saved-view key, ADR-0129 D1–D2). Composing N stacks under a pick strategy loses N−1 package identities — the lossiness ADR-0130 section 5 rejects composeStacks-as-is for. Both cases are real, so this is an added value, not a change of meaning for the existing ones.

What the mode does

Which entries a stack contributes is D4's read-both rule applied to the inputs — the same rule the load path applies to an artifact, so composition and loading cannot disagree about what "the packages of this stack" means:

• stack declares packages → those entries;
• stack declares no packages → its singular manifest as a single-element list.

A stack carrying both therefore contributes its list once, not its list plus its manifest — nothing is emitted twice in the first place, so there is no de-duplication pass to get wrong later.

Every emitted element is the { manifest: ... } wrapper object, reusing ArtifactPackageEntrySchema (landed by #14191). ⛔ The wrapper shape is not re-derived — a second declaration of one shape is the drift ADR-0116 exists about, and D4 reserved that exact position so a future { ref, integrity } segment stays an additive key rather than a reshape. The pins assert it by feeding composed output to that schema rather than to a literal.

'preserve' is additive over the default, not a fourth pick: the singular manifest is still selected by the same 'last' rule, so a preserve composition's output is the default's output plus the package list. The artifact keeps an artifact-level identity (D6 — one artifact, one version) and no consumer reading composed.manifest sees a key disappear. Nothing is registered twice either: D4's read-both rule reads a packages-carrying artifact through packages, and manifest is the fallback branch for artifacts that have none.

packages' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and keeps its meaning. Preserve composes packages itself and concatenates in stack order too, so the two agree rather than compete — pinned as an equality where every stack carries packages.

The pin #14191 left on purpose — updated, not deleted

#14191 left leaves the singular manifest pick-one semantics alone in packages/spec/src/stack-artifact-packages.test.ts so this follow-up would be a visible change rather than a silent one. It is retitled ... BY DEFAULT, and here is what it now records: its assertions did not move. Preserve is opt-in, the default is still 'last', and a caller passing no options gets what it got before — one manifest kept, and no packages key minted underneath it. Only the pin's stated reason changed, from "until the follow-up lands" to "the follow-up landed and deliberately did not touch this path". ⛔ It was not deleted to make a suite green; the preserve mode's own behaviour is pinned in a separate file.

Reverse verification — red to green

Ablation: if (opts.manifest === 'preserve') { in packages/spec/src/stack.zod.ts replaced by if (false) {, so preserve falls through to the default and builds no list.

• The mutation reached what the test resolves. The pins import ./stack.zod relatively, so vitest resolves package source, not dist — the mutated file is the file under test, and no build stands between them. Confirmed on disk before reading any result, anchored on the text being changed rather than on the editor's exit code: injected-count 1, removed-count 0, and blob b540201d moving to 7bf25448.
• Mutated leg: 7 failed | 71 passed — the preserve pins are red; the 'first' / 'last' / index pins stay green, which is the correct direction (they must be unaffected by the new branch).
• Restore leg, proven by bytes: restored with git checkout HEAD -- FILEPATH — pinned to HEAD rather than the bare form, which reads the index the mutation may have polluted, and with an absolute path resolved from git rev-parse --show-toplevel rather than a relative one. Working blob back to b540201d = the HEAD blob, git diff HEAD empty. Restored run: 78 passed (78).

The first ablation pass reported 5 red, not 7 — it caught two vacuously-green pins of my own: a for over an absent packages list iterates zero times, and "the output is the default's output plus the list" holds trivially when the list is never added. Both were fixed to assert the addition first (commit a47ef393) before the second pass measured 7.

Verification

Union re-run at final commit a47ef393; the tree was clean for every run below.

• pnpm --filter @objectstack/spec exec vitest run — 450 files, 12068 tests, all passed (exit 0)
• 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)
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (52 commands): 47 exit 0. The other 5 are PREREQUISITE NOT MET / NOT MEASURED, not findings — check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt and check:doc-formula-expressions all want the whole workspace built (66 of 67 packages have no dist/), and check-test-completeness / check-half-states exit 3 by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally; check:api-surface then passed on real declarations (exit 0). CI owns the repo-scale remainder.
• Lint, as a declared narrowing — eslint --no-inline-config --format json over the 3 changed source files: 3 files linted, 0 errors, 0 warnings. The narrowing is a measurement, not a skip: the population is read from eslint's own config (--print-config resolves for each file, exit 0), the count is read from the JSON output, and the invariance holds 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.

Changeset

.changeset/adr0130-composestacks-manifest-preserve.md — @objectstack/spec: minor. A pure widening: the accept set gained exactly one option value, the default is still 'last', no existing value changed meaning, and nothing that parsed before is refused now. The refusal of a neighbouring spelling is pinned alongside the acceptance, so "widened by exactly one" is measured rather than asserted.

Clause-② — yes, and this PR stays draft

Both limbs are hit: the path limb (packages/spec/src/**) and the content limb (a new public option value widens the accept set). needs:contract-review is attached and the PR is draft pending that review.

⚠️ An independent review is required. A verdict rendered by the session that wrote this diff does not satisfy the independence the gate wants — recorded as a process finding on #14191.

The one judgement call a reviewer should look at first: preserve retains the singular manifest (selected by 'last') instead of clearing it. The reasoning is above — additive rather than key-removing, D6's artifact-level identity, and D4's read-both rule making double registration impossible. ADR-0130 does not pin this either way, so it is the decision most worth a second opinion.

⛔ Scope: this ships composition only. The load path that iterates packages in dependency-topological order (D5, through resolvePluginOrder) and the installPackage co-ownership gate (D1/D3) are separate, dependent cards. Composing with 'preserve' today registers no extra package.

Authored in Claude Code session session_01UHvF5hyiZjnCyExFnfQB8m (https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m) — kept in prose because a body edit rewrites the footer's session URL to the bare form.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0185976db0933f220d40f2982ad111f31a2709da — the merge of head a47ef3932791047aacabed1d0386ef6d211fc87a into base 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2, 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 0185976db0933f220d40f2982ad111f31a2709da && git checkout 0185976db0933f220d40f2982ad111f31a2709da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 a47ef3932791047aacabed1d0386ef6d211fc87a && git checkout -B drift-repro 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 && git merge --no-ff a47ef3932791047aacabed1d0386ef6d211fc87a
node scripts/docs-audit/affected-docs.mjs --json 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2

⚠️ 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[hotlong]

CI 全绿；唯一未决项是独立 Clause-② 复审，⛔ 本会话不代劳

a47ef393 上 48 项检查全部完成，无一失败（success 或 skipped）。六个必需上下文按 check-run 名称逐个核对（AGENTS.md §522：必需集按名匹配，改名会静默脱钩，所以按名核而不是按数）：

必需上下文	结论
Lint & Repo Gates	✅ success (14:51:34)
TypeScript Type Check	✅ success
Test Core	✅ success — 汇总 + 6 分片全过
Dogfood Regression Gate	✅ success — 汇总 + 3 分片全过
Build Core	✅ success
Temporal Conformance (live PG + MySQL)	✅ success

Governed Surface Queue Guard 亦 success；Flag docs affected by code changes 的 advisory 已单独核过——两页命中页（getting-started/examples.mdx、glossary.mdx）都没有对 manifest 取值做封闭枚举，'preserve' 叠加后两页逐字仍成立，无文档改动可欠；第三页 content/docs/releases/v17.mdx 是 release-owned，只读不碰。

---

为什么它仍然是 draft，以及我不做什么

⛔ 本 PR 保持 draft，我不 arm auto-merge、不翻 ready。 §522 的前置是"已绿 且已接受 且非 draft"三者齐备；这里只满足第一条。

⛔ Clause-② 的裁决不由本会话作出。 这个 diff 是本会话（session_01UHvF5hyiZjnCyExFnfQB8m）派发并署名的，写 diff 的一方自审不满足该门要求的独立性——这正是 #14191 上记录在案的 process finding，不重蹈。

需要的就一件事：一次独立的 Clause-② 复审。PR 正文已把最该要第二意见的那处判断题标了出来——preserve 保留单数 manifest（按 'last' 选）而非清空它，理由是叠加而非删键、D6 的物级身份、以及 D4 的 read-both 规则使重复注册不可能；ADR-0130 两边都没钉死，所以它是决定性的一处，不是风格问题。

复审通过后即可 ready → 合并队列。在那之前它就该停在这里。

---

Generated by Claude Code

[huangyiirene]

契约复审:PASS —— head a47ef393,同笔清标 + 转 ready + 挂 auto-merge

项目总监席契约复审记录 · session session_01KGtaLpkW1mycWgkbSb3H6t · 档位机读认定在案(claude-fable-5 = CONTRACT_REVIEW_TIER)· 独立性成立(复审会话 ≠ 署名会话 session_01UHvF5hyiZjnCyExFnfQB8m,#14191 的 process finding 得到满足)· 对全 diff 复审(4 文件 +535/−17),⛔ 非对报告。

被点名的判断题,本席审定:保留单数 manifest 正确,维持

PR 正文与车道都把这一处交给第二意见 —— preserve 保留单数 manifest(按 'last' 选)而非清空。三条理由逐一对树核验成立:

1. 无重复注册的机械保证:D4 read-both 规则(feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 落的那条)规定「有 packages ⇒ 走 packages,manifest 是无 packages 时的回退支」—— preserve 输出必带 packages,故其 manifest 永不被当包迭代;
2. D6 物级身份:一件 artifact 一个版本,清空 manifest 反而把 artifact 级身份留空;
3. 加法不删键:读 composed.manifest 的既有消费者看不到键消失。
   ⇒ ADR-0130 未钉的这一处由本复审钉下:preserve = 默认输出 + 包清单,后来者⛔ 不得改为清空式。

条款②与裁决符合性

1. 双肢命中如实申报(spec 路径 + 新公开选项值),draft 候审姿态正确;
2. 恰好加宽一个值,测量而非断言 ✅ —— 邻拼写(preserve-all)与负索引拒绝同钉,默认值 'last' 单独钉(选项 schema parse),default-未动的负半(三个 pick 策略都不铸 packages 键)钉住 —— D7「Reviewer attention is not a mechanism」被照字面执行;
3. read-both 规则单源 ✅ —— preservePackageEntries 应用的是 D4 同一规则(带双备键的 stack 只贡献一次),wrapper 形状以 ArtifactPackageEntrySchema 判而非重declare(ADR-0116 漂移防线),平铺体拒绝作负对照;与 COMPOSE_KEY_DISPOSITIONS 的 'concat' 一致性钉为相等式;
4. feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 留置哨钉的处置正确 ✅ —— 断言未动、只改陈述理由并改题为 BY DEFAULT,哨钉的「让后续变更可见」使命完成而非被删绿;
5. 消融自纠入册 ✅ —— 首轮 5 红暴露两枚自写的空洞钉(零次迭代恒绿、加法未发生时平凡成立),修钉后二轮 7 红恰合预declare —— 这是消融纪律的教科书用法;字节还原证明齐;
6. 单栈短路按身份返回的钉与理由(单 manifest 即 read-both 支 2 的「一个包」)成立;changeset minor 纯加宽定级正确;12068 测试绿,车道已按名核六必需上下文全绿,文档漂移两命中页无封闭枚举、零欠账。

范围内观察(⛔ 不阻落地,记给 D1/D3 实施者):preserve 不去重 —— 两个输入若携带同一 manifest.id,包清单出现重复条目;按 ADR-0130 分工,拒绝重复身份属 installPackage 共有权门(D1/D3)的裁量,组合期不预判。届时该卡请带上这一读数。

收口(同笔)

needs:contract-review 摘除 → draft 转 ready → auto-merge 挂上(合并队列资格 = 全检查绿,已满足)。落地即 Fixes #14164 关卡。

---

Generated by Claude Code

[hotlong]

Fixes#14164

Implements ADR-0130's Consequences follow-up row 3. composeStacks' manifest option accepts a fourth value, 'preserve': instead of keeping one manifest and discarding the rest, it folds every input's package identity into the composed artifact's packages list (ADR-0130 D4), in stack order.

Why a new value rather than a fix to the old ones

manifest: 'first' | 'last' | index is a deliberate pick-one, and it is correct for the case it was written for — several stacks assembled into ONE published package, which has one identity. ADR-0130 introduces the other case: a release artifact that carries N packages, each keeping its own identity, so a product splits into modules without renaming a single object (the object name IS the table name, the REST path, the formula token and the saved-view key, ADR-0129 D1–D2). Composing N stacks under a pick strategy loses N−1 package identities — the lossiness ADR-0130 section 5 rejects composeStacks-as-is for. Both cases are real, so this is an added value, not a change of meaning for the existing ones.

What the mode does

Which entries a stack contributes is D4's read-both rule applied to the inputs — the same rule the load path applies to an artifact, so composition and loading cannot disagree about what "the packages of this stack" means:

• stack declares packages → those entries;
• stack declares no packages → its singular manifest as a single-element list.

A stack carrying both therefore contributes its list once, not its list plus its manifest — nothing is emitted twice in the first place, so there is no de-duplication pass to get wrong later.

Every emitted element is the { manifest: ... } wrapper object, reusing ArtifactPackageEntrySchema (landed by #14191). ⛔ The wrapper shape is not re-derived — a second declaration of one shape is the drift ADR-0116 exists about, and D4 reserved that exact position so a future { ref, integrity } segment stays an additive key rather than a reshape. The pins assert it by feeding composed output to that schema rather than to a literal.

'preserve' is additive over the default, not a fourth pick: the singular manifest is still selected by the same 'last' rule, so a preserve composition's output is the default's output plus the package list. The artifact keeps an artifact-level identity (D6 — one artifact, one version) and no consumer reading composed.manifest sees a key disappear. Nothing is registered twice either: D4's read-both rule reads a packages-carrying artifact through packages, and manifest is the fallback branch for artifacts that have none.

packages' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and keeps its meaning. Preserve composes packages itself and concatenates in stack order too, so the two agree rather than compete — pinned as an equality where every stack carries packages.

The pin #14191 left on purpose — updated, not deleted

#14191 left leaves the singular manifest pick-one semantics alone in packages/spec/src/stack-artifact-packages.test.ts so this follow-up would be a visible change rather than a silent one. It is retitled ... BY DEFAULT, and here is what it now records: its assertions did not move. Preserve is opt-in, the default is still 'last', and a caller passing no options gets what it got before — one manifest kept, and no packages key minted underneath it. Only the pin's stated reason changed, from "until the follow-up lands" to "the follow-up landed and deliberately did not touch this path". ⛔ It was not deleted to make a suite green; the preserve mode's own behaviour is pinned in a separate file.

Reverse verification — red to green

Ablation: if (opts.manifest === 'preserve') { in packages/spec/src/stack.zod.ts replaced by if (false) {, so preserve falls through to the default and builds no list.

• The mutation reached what the test resolves. The pins import ./stack.zod relatively, so vitest resolves package source, not dist — the mutated file is the file under test, and no build stands between them. Confirmed on disk before reading any result, anchored on the text being changed rather than on the editor's exit code: injected-count 1, removed-count 0, and blob b540201d moving to 7bf25448.
• Mutated leg: 7 failed | 71 passed — the preserve pins are red; the 'first' / 'last' / index pins stay green, which is the correct direction (they must be unaffected by the new branch).
• Restore leg, proven by bytes: restored with git checkout HEAD -- FILEPATH — pinned to HEAD rather than the bare form, which reads the index the mutation may have polluted, and with an absolute path resolved from git rev-parse --show-toplevel rather than a relative one. Working blob back to b540201d = the HEAD blob, git diff HEAD empty. Restored run: 78 passed (78).

The first ablation pass reported 5 red, not 7 — it caught two vacuously-green pins of my own: a for over an absent packages list iterates zero times, and "the output is the default's output plus the list" holds trivially when the list is never added. Both were fixed to assert the addition first (commit a47ef393) before the second pass measured 7.

Verification

Union re-run at final commit a47ef393; the tree was clean for every run below.

• pnpm --filter @objectstack/spec exec vitest run — 450 files, 12068 tests, all passed (exit 0)
• 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)
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (52 commands): 47 exit 0. The other 5 are PREREQUISITE NOT MET / NOT MEASURED, not findings — check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt and check:doc-formula-expressions all want the whole workspace built (66 of 67 packages have no dist/), and check-test-completeness / check-half-states exit 3 by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally; check:api-surface then passed on real declarations (exit 0). CI owns the repo-scale remainder.
• Lint, as a declared narrowing — eslint --no-inline-config --format json over the 3 changed source files: 3 files linted, 0 errors, 0 warnings. The narrowing is a measurement, not a skip: the population is read from eslint's own config (--print-config resolves for each file, exit 0), the count is read from the JSON output, and the invariance holds 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.

Changeset

.changeset/adr0130-composestacks-manifest-preserve.md — @objectstack/spec: minor. A pure widening: the accept set gained exactly one option value, the default is still 'last', no existing value changed meaning, and nothing that parsed before is refused now. The refusal of a neighbouring spelling is pinned alongside the acceptance, so "widened by exactly one" is measured rather than asserted.

Clause-② — yes, and this PR stays draft

Both limbs are hit: the path limb (packages/spec/src/**) and the content limb (a new public option value widens the accept set). needs:contract-review is attached and the PR is draft pending that review.

⚠️ An independent review is required. A verdict rendered by the session that wrote this diff does not satisfy the independence the gate wants — recorded as a process finding on #14191.

The one judgement call a reviewer should look at first: preserve retains the singular manifest (selected by 'last') instead of clearing it. The reasoning is above — additive rather than key-removing, D6's artifact-level identity, and D4's read-both rule making double registration impossible. ADR-0130 does not pin this either way, so it is the decision most worth a second opinion.

⛔ Scope: this ships composition only. The load path that iterates packages in dependency-topological order (D5, through resolvePluginOrder) and the installPackage co-ownership gate (D1/D3) are separate, dependent cards. Composing with 'preserve' today registers no extra package.

Authored in Claude Code session session_01UHvF5hyiZjnCyExFnfQB8m (https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m) — kept in prose because a body edit rewrites the footer's session URL to the bare form.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0185976db0933f220d40f2982ad111f31a2709da — the merge of head a47ef3932791047aacabed1d0386ef6d211fc87a into base 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2, 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 0185976db0933f220d40f2982ad111f31a2709da && git checkout 0185976db0933f220d40f2982ad111f31a2709da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 a47ef3932791047aacabed1d0386ef6d211fc87a && git checkout -B drift-repro 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 && git merge --no-ff a47ef3932791047aacabed1d0386ef6d211fc87a
node scripts/docs-audit/affected-docs.mjs --json 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2

⚠️ 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[hotlong]

CI 全绿；唯一未决项是独立 Clause-② 复审，⛔ 本会话不代劳

a47ef393 上 48 项检查全部完成，无一失败（success 或 skipped）。六个必需上下文按 check-run 名称逐个核对（AGENTS.md §522：必需集按名匹配，改名会静默脱钩，所以按名核而不是按数）：

必需上下文	结论
Lint & Repo Gates	✅ success (14:51:34)
TypeScript Type Check	✅ success
Test Core	✅ success — 汇总 + 6 分片全过
Dogfood Regression Gate	✅ success — 汇总 + 3 分片全过
Build Core	✅ success
Temporal Conformance (live PG + MySQL)	✅ success

Governed Surface Queue Guard 亦 success；Flag docs affected by code changes 的 advisory 已单独核过——两页命中页（getting-started/examples.mdx、glossary.mdx）都没有对 manifest 取值做封闭枚举，'preserve' 叠加后两页逐字仍成立，无文档改动可欠；第三页 content/docs/releases/v17.mdx 是 release-owned，只读不碰。

---

为什么它仍然是 draft，以及我不做什么

⛔ 本 PR 保持 draft，我不 arm auto-merge、不翻 ready。 §522 的前置是"已绿 且已接受 且非 draft"三者齐备；这里只满足第一条。

⛔ Clause-② 的裁决不由本会话作出。 这个 diff 是本会话（session_01UHvF5hyiZjnCyExFnfQB8m）派发并署名的，写 diff 的一方自审不满足该门要求的独立性——这正是 #14191 上记录在案的 process finding，不重蹈。

需要的就一件事：一次独立的 Clause-② 复审。PR 正文已把最该要第二意见的那处判断题标了出来——preserve 保留单数 manifest（按 'last' 选）而非清空它，理由是叠加而非删键、D6 的物级身份、以及 D4 的 read-both 规则使重复注册不可能；ADR-0130 两边都没钉死，所以它是决定性的一处，不是风格问题。

复审通过后即可 ready → 合并队列。在那之前它就该停在这里。

---

Generated by Claude Code

[huangyiirene]

契约复审:PASS —— head a47ef393,同笔清标 + 转 ready + 挂 auto-merge

项目总监席契约复审记录 · session session_01KGtaLpkW1mycWgkbSb3H6t · 档位机读认定在案(claude-fable-5 = CONTRACT_REVIEW_TIER)· 独立性成立(复审会话 ≠ 署名会话 session_01UHvF5hyiZjnCyExFnfQB8m,#14191 的 process finding 得到满足)· 对全 diff 复审(4 文件 +535/−17),⛔ 非对报告。

被点名的判断题,本席审定:保留单数 manifest 正确,维持

PR 正文与车道都把这一处交给第二意见 —— preserve 保留单数 manifest(按 'last' 选)而非清空。三条理由逐一对树核验成立:

1. 无重复注册的机械保证:D4 read-both 规则(feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 落的那条)规定「有 packages ⇒ 走 packages,manifest 是无 packages 时的回退支」—— preserve 输出必带 packages,故其 manifest 永不被当包迭代;
2. D6 物级身份:一件 artifact 一个版本,清空 manifest 反而把 artifact 级身份留空;
3. 加法不删键:读 composed.manifest 的既有消费者看不到键消失。
   ⇒ ADR-0130 未钉的这一处由本复审钉下:preserve = 默认输出 + 包清单,后来者⛔ 不得改为清空式。

条款②与裁决符合性

1. 双肢命中如实申报(spec 路径 + 新公开选项值),draft 候审姿态正确;
2. 恰好加宽一个值,测量而非断言 ✅ —— 邻拼写(preserve-all)与负索引拒绝同钉,默认值 'last' 单独钉(选项 schema parse),default-未动的负半(三个 pick 策略都不铸 packages 键)钉住 —— D7「Reviewer attention is not a mechanism」被照字面执行;
3. read-both 规则单源 ✅ —— preservePackageEntries 应用的是 D4 同一规则(带双备键的 stack 只贡献一次),wrapper 形状以 ArtifactPackageEntrySchema 判而非重declare(ADR-0116 漂移防线),平铺体拒绝作负对照;与 COMPOSE_KEY_DISPOSITIONS 的 'concat' 一致性钉为相等式;
4. feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 留置哨钉的处置正确 ✅ —— 断言未动、只改陈述理由并改题为 BY DEFAULT,哨钉的「让后续变更可见」使命完成而非被删绿;
5. 消融自纠入册 ✅ —— 首轮 5 红暴露两枚自写的空洞钉(零次迭代恒绿、加法未发生时平凡成立),修钉后二轮 7 红恰合预declare —— 这是消融纪律的教科书用法;字节还原证明齐;
6. 单栈短路按身份返回的钉与理由(单 manifest 即 read-both 支 2 的「一个包」)成立;changeset minor 纯加宽定级正确;12068 测试绿,车道已按名核六必需上下文全绿,文档漂移两命中页无封闭枚举、零欠账。

范围内观察(⛔ 不阻落地,记给 D1/D3 实施者):preserve 不去重 —— 两个输入若携带同一 manifest.id,包清单出现重复条目;按 ADR-0130 分工,拒绝重复身份属 installPackage 共有权门(D1/D3)的裁量,组合期不预判。届时该卡请带上这一读数。

收口(同笔)

needs:contract-review 摘除 → draft 转 ready → auto-merge 挂上(合并队列资格 = 全检查绿,已满足)。落地即 Fixes #14164 关卡。

---

Generated by Claude Code

[hotlong]

Fixes#14164

Implements ADR-0130's Consequences follow-up row 3. composeStacks' manifest option accepts a fourth value, 'preserve': instead of keeping one manifest and discarding the rest, it folds every input's package identity into the composed artifact's packages list (ADR-0130 D4), in stack order.

Why a new value rather than a fix to the old ones

manifest: 'first' | 'last' | index is a deliberate pick-one, and it is correct for the case it was written for — several stacks assembled into ONE published package, which has one identity. ADR-0130 introduces the other case: a release artifact that carries N packages, each keeping its own identity, so a product splits into modules without renaming a single object (the object name IS the table name, the REST path, the formula token and the saved-view key, ADR-0129 D1–D2). Composing N stacks under a pick strategy loses N−1 package identities — the lossiness ADR-0130 section 5 rejects composeStacks-as-is for. Both cases are real, so this is an added value, not a change of meaning for the existing ones.

What the mode does

Which entries a stack contributes is D4's read-both rule applied to the inputs — the same rule the load path applies to an artifact, so composition and loading cannot disagree about what "the packages of this stack" means:

• stack declares packages → those entries;
• stack declares no packages → its singular manifest as a single-element list.

A stack carrying both therefore contributes its list once, not its list plus its manifest — nothing is emitted twice in the first place, so there is no de-duplication pass to get wrong later.

Every emitted element is the { manifest: ... } wrapper object, reusing ArtifactPackageEntrySchema (landed by #14191). ⛔ The wrapper shape is not re-derived — a second declaration of one shape is the drift ADR-0116 exists about, and D4 reserved that exact position so a future { ref, integrity } segment stays an additive key rather than a reshape. The pins assert it by feeding composed output to that schema rather than to a literal.

'preserve' is additive over the default, not a fourth pick: the singular manifest is still selected by the same 'last' rule, so a preserve composition's output is the default's output plus the package list. The artifact keeps an artifact-level identity (D6 — one artifact, one version) and no consumer reading composed.manifest sees a key disappear. Nothing is registered twice either: D4's read-both rule reads a packages-carrying artifact through packages, and manifest is the fallback branch for artifacts that have none.

packages' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and keeps its meaning. Preserve composes packages itself and concatenates in stack order too, so the two agree rather than compete — pinned as an equality where every stack carries packages.

The pin #14191 left on purpose — updated, not deleted

#14191 left leaves the singular manifest pick-one semantics alone in packages/spec/src/stack-artifact-packages.test.ts so this follow-up would be a visible change rather than a silent one. It is retitled ... BY DEFAULT, and here is what it now records: its assertions did not move. Preserve is opt-in, the default is still 'last', and a caller passing no options gets what it got before — one manifest kept, and no packages key minted underneath it. Only the pin's stated reason changed, from "until the follow-up lands" to "the follow-up landed and deliberately did not touch this path". ⛔ It was not deleted to make a suite green; the preserve mode's own behaviour is pinned in a separate file.

Reverse verification — red to green

Ablation: if (opts.manifest === 'preserve') { in packages/spec/src/stack.zod.ts replaced by if (false) {, so preserve falls through to the default and builds no list.

• The mutation reached what the test resolves. The pins import ./stack.zod relatively, so vitest resolves package source, not dist — the mutated file is the file under test, and no build stands between them. Confirmed on disk before reading any result, anchored on the text being changed rather than on the editor's exit code: injected-count 1, removed-count 0, and blob b540201d moving to 7bf25448.
• Mutated leg: 7 failed | 71 passed — the preserve pins are red; the 'first' / 'last' / index pins stay green, which is the correct direction (they must be unaffected by the new branch).
• Restore leg, proven by bytes: restored with git checkout HEAD -- FILEPATH — pinned to HEAD rather than the bare form, which reads the index the mutation may have polluted, and with an absolute path resolved from git rev-parse --show-toplevel rather than a relative one. Working blob back to b540201d = the HEAD blob, git diff HEAD empty. Restored run: 78 passed (78).

The first ablation pass reported 5 red, not 7 — it caught two vacuously-green pins of my own: a for over an absent packages list iterates zero times, and "the output is the default's output plus the list" holds trivially when the list is never added. Both were fixed to assert the addition first (commit a47ef393) before the second pass measured 7.

Verification

Union re-run at final commit a47ef393; the tree was clean for every run below.

• pnpm --filter @objectstack/spec exec vitest run — 450 files, 12068 tests, all passed (exit 0)
• 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)
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (52 commands): 47 exit 0. The other 5 are PREREQUISITE NOT MET / NOT MEASURED, not findings — check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt and check:doc-formula-expressions all want the whole workspace built (66 of 67 packages have no dist/), and check-test-completeness / check-half-states exit 3 by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally; check:api-surface then passed on real declarations (exit 0). CI owns the repo-scale remainder.
• Lint, as a declared narrowing — eslint --no-inline-config --format json over the 3 changed source files: 3 files linted, 0 errors, 0 warnings. The narrowing is a measurement, not a skip: the population is read from eslint's own config (--print-config resolves for each file, exit 0), the count is read from the JSON output, and the invariance holds 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.

Changeset

.changeset/adr0130-composestacks-manifest-preserve.md — @objectstack/spec: minor. A pure widening: the accept set gained exactly one option value, the default is still 'last', no existing value changed meaning, and nothing that parsed before is refused now. The refusal of a neighbouring spelling is pinned alongside the acceptance, so "widened by exactly one" is measured rather than asserted.

Clause-② — yes, and this PR stays draft

Both limbs are hit: the path limb (packages/spec/src/**) and the content limb (a new public option value widens the accept set). needs:contract-review is attached and the PR is draft pending that review.

⚠️ An independent review is required. A verdict rendered by the session that wrote this diff does not satisfy the independence the gate wants — recorded as a process finding on #14191.

The one judgement call a reviewer should look at first: preserve retains the singular manifest (selected by 'last') instead of clearing it. The reasoning is above — additive rather than key-removing, D6's artifact-level identity, and D4's read-both rule making double registration impossible. ADR-0130 does not pin this either way, so it is the decision most worth a second opinion.

⛔ Scope: this ships composition only. The load path that iterates packages in dependency-topological order (D5, through resolvePluginOrder) and the installPackage co-ownership gate (D1/D3) are separate, dependent cards. Composing with 'preserve' today registers no extra package.

Authored in Claude Code session session_01UHvF5hyiZjnCyExFnfQB8m (https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m) — kept in prose because a body edit rewrites the footer's session URL to the bare form.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0185976db0933f220d40f2982ad111f31a2709da — the merge of head a47ef3932791047aacabed1d0386ef6d211fc87a into base 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2, 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 0185976db0933f220d40f2982ad111f31a2709da && git checkout 0185976db0933f220d40f2982ad111f31a2709da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 a47ef3932791047aacabed1d0386ef6d211fc87a && git checkout -B drift-repro 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 && git merge --no-ff a47ef3932791047aacabed1d0386ef6d211fc87a
node scripts/docs-audit/affected-docs.mjs --json 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2

⚠️ 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[hotlong]

CI 全绿；唯一未决项是独立 Clause-② 复审，⛔ 本会话不代劳

a47ef393 上 48 项检查全部完成，无一失败（success 或 skipped）。六个必需上下文按 check-run 名称逐个核对（AGENTS.md §522：必需集按名匹配，改名会静默脱钩，所以按名核而不是按数）：

必需上下文	结论
Lint & Repo Gates	✅ success (14:51:34)
TypeScript Type Check	✅ success
Test Core	✅ success — 汇总 + 6 分片全过
Dogfood Regression Gate	✅ success — 汇总 + 3 分片全过
Build Core	✅ success
Temporal Conformance (live PG + MySQL)	✅ success

Governed Surface Queue Guard 亦 success；Flag docs affected by code changes 的 advisory 已单独核过——两页命中页（getting-started/examples.mdx、glossary.mdx）都没有对 manifest 取值做封闭枚举，'preserve' 叠加后两页逐字仍成立，无文档改动可欠；第三页 content/docs/releases/v17.mdx 是 release-owned，只读不碰。

---

为什么它仍然是 draft，以及我不做什么

⛔ 本 PR 保持 draft，我不 arm auto-merge、不翻 ready。 §522 的前置是"已绿 且已接受 且非 draft"三者齐备；这里只满足第一条。

⛔ Clause-② 的裁决不由本会话作出。 这个 diff 是本会话（session_01UHvF5hyiZjnCyExFnfQB8m）派发并署名的，写 diff 的一方自审不满足该门要求的独立性——这正是 #14191 上记录在案的 process finding，不重蹈。

需要的就一件事：一次独立的 Clause-② 复审。PR 正文已把最该要第二意见的那处判断题标了出来——preserve 保留单数 manifest（按 'last' 选）而非清空它，理由是叠加而非删键、D6 的物级身份、以及 D4 的 read-both 规则使重复注册不可能；ADR-0130 两边都没钉死，所以它是决定性的一处，不是风格问题。

复审通过后即可 ready → 合并队列。在那之前它就该停在这里。

---

Generated by Claude Code

[huangyiirene]

契约复审:PASS —— head a47ef393,同笔清标 + 转 ready + 挂 auto-merge

项目总监席契约复审记录 · session session_01KGtaLpkW1mycWgkbSb3H6t · 档位机读认定在案(claude-fable-5 = CONTRACT_REVIEW_TIER)· 独立性成立(复审会话 ≠ 署名会话 session_01UHvF5hyiZjnCyExFnfQB8m,#14191 的 process finding 得到满足)· 对全 diff 复审(4 文件 +535/−17),⛔ 非对报告。

被点名的判断题,本席审定:保留单数 manifest 正确,维持

PR 正文与车道都把这一处交给第二意见 —— preserve 保留单数 manifest(按 'last' 选)而非清空。三条理由逐一对树核验成立:

1. 无重复注册的机械保证:D4 read-both 规则(feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 落的那条)规定「有 packages ⇒ 走 packages,manifest 是无 packages 时的回退支」—— preserve 输出必带 packages,故其 manifest 永不被当包迭代;
2. D6 物级身份:一件 artifact 一个版本,清空 manifest 反而把 artifact 级身份留空;
3. 加法不删键:读 composed.manifest 的既有消费者看不到键消失。
   ⇒ ADR-0130 未钉的这一处由本复审钉下:preserve = 默认输出 + 包清单,后来者⛔ 不得改为清空式。

条款②与裁决符合性

1. 双肢命中如实申报(spec 路径 + 新公开选项值),draft 候审姿态正确;
2. 恰好加宽一个值,测量而非断言 ✅ —— 邻拼写(preserve-all)与负索引拒绝同钉,默认值 'last' 单独钉(选项 schema parse),default-未动的负半(三个 pick 策略都不铸 packages 键)钉住 —— D7「Reviewer attention is not a mechanism」被照字面执行;
3. read-both 规则单源 ✅ —— preservePackageEntries 应用的是 D4 同一规则(带双备键的 stack 只贡献一次),wrapper 形状以 ArtifactPackageEntrySchema 判而非重declare(ADR-0116 漂移防线),平铺体拒绝作负对照;与 COMPOSE_KEY_DISPOSITIONS 的 'concat' 一致性钉为相等式;
4. feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 留置哨钉的处置正确 ✅ —— 断言未动、只改陈述理由并改题为 BY DEFAULT,哨钉的「让后续变更可见」使命完成而非被删绿;
5. 消融自纠入册 ✅ —— 首轮 5 红暴露两枚自写的空洞钉(零次迭代恒绿、加法未发生时平凡成立),修钉后二轮 7 红恰合预declare —— 这是消融纪律的教科书用法;字节还原证明齐;
6. 单栈短路按身份返回的钉与理由(单 manifest 即 read-both 支 2 的「一个包」)成立;changeset minor 纯加宽定级正确;12068 测试绿,车道已按名核六必需上下文全绿,文档漂移两命中页无封闭枚举、零欠账。

范围内观察(⛔ 不阻落地,记给 D1/D3 实施者):preserve 不去重 —— 两个输入若携带同一 manifest.id,包清单出现重复条目;按 ADR-0130 分工,拒绝重复身份属 installPackage 共有权门(D1/D3)的裁量,组合期不预判。届时该卡请带上这一读数。

收口(同笔)

needs:contract-review 摘除 → draft 转 ready → auto-merge 挂上(合并队列资格 = 全检查绿,已满足)。落地即 Fixes #14164 关卡。

---

Generated by Claude Code

[hotlong]

Fixes#14164

Implements ADR-0130's Consequences follow-up row 3. composeStacks' manifest option accepts a fourth value, 'preserve': instead of keeping one manifest and discarding the rest, it folds every input's package identity into the composed artifact's packages list (ADR-0130 D4), in stack order.

Why a new value rather than a fix to the old ones

manifest: 'first' | 'last' | index is a deliberate pick-one, and it is correct for the case it was written for — several stacks assembled into ONE published package, which has one identity. ADR-0130 introduces the other case: a release artifact that carries N packages, each keeping its own identity, so a product splits into modules without renaming a single object (the object name IS the table name, the REST path, the formula token and the saved-view key, ADR-0129 D1–D2). Composing N stacks under a pick strategy loses N−1 package identities — the lossiness ADR-0130 section 5 rejects composeStacks-as-is for. Both cases are real, so this is an added value, not a change of meaning for the existing ones.

What the mode does

Which entries a stack contributes is D4's read-both rule applied to the inputs — the same rule the load path applies to an artifact, so composition and loading cannot disagree about what "the packages of this stack" means:

• stack declares packages → those entries;
• stack declares no packages → its singular manifest as a single-element list.

A stack carrying both therefore contributes its list once, not its list plus its manifest — nothing is emitted twice in the first place, so there is no de-duplication pass to get wrong later.

Every emitted element is the { manifest: ... } wrapper object, reusing ArtifactPackageEntrySchema (landed by #14191). ⛔ The wrapper shape is not re-derived — a second declaration of one shape is the drift ADR-0116 exists about, and D4 reserved that exact position so a future { ref, integrity } segment stays an additive key rather than a reshape. The pins assert it by feeding composed output to that schema rather than to a literal.

'preserve' is additive over the default, not a fourth pick: the singular manifest is still selected by the same 'last' rule, so a preserve composition's output is the default's output plus the package list. The artifact keeps an artifact-level identity (D6 — one artifact, one version) and no consumer reading composed.manifest sees a key disappear. Nothing is registered twice either: D4's read-both rule reads a packages-carrying artifact through packages, and manifest is the fallback branch for artifacts that have none.

packages' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and keeps its meaning. Preserve composes packages itself and concatenates in stack order too, so the two agree rather than compete — pinned as an equality where every stack carries packages.

The pin #14191 left on purpose — updated, not deleted

#14191 left leaves the singular manifest pick-one semantics alone in packages/spec/src/stack-artifact-packages.test.ts so this follow-up would be a visible change rather than a silent one. It is retitled ... BY DEFAULT, and here is what it now records: its assertions did not move. Preserve is opt-in, the default is still 'last', and a caller passing no options gets what it got before — one manifest kept, and no packages key minted underneath it. Only the pin's stated reason changed, from "until the follow-up lands" to "the follow-up landed and deliberately did not touch this path". ⛔ It was not deleted to make a suite green; the preserve mode's own behaviour is pinned in a separate file.

Reverse verification — red to green

Ablation: if (opts.manifest === 'preserve') { in packages/spec/src/stack.zod.ts replaced by if (false) {, so preserve falls through to the default and builds no list.

• The mutation reached what the test resolves. The pins import ./stack.zod relatively, so vitest resolves package source, not dist — the mutated file is the file under test, and no build stands between them. Confirmed on disk before reading any result, anchored on the text being changed rather than on the editor's exit code: injected-count 1, removed-count 0, and blob b540201d moving to 7bf25448.
• Mutated leg: 7 failed | 71 passed — the preserve pins are red; the 'first' / 'last' / index pins stay green, which is the correct direction (they must be unaffected by the new branch).
• Restore leg, proven by bytes: restored with git checkout HEAD -- FILEPATH — pinned to HEAD rather than the bare form, which reads the index the mutation may have polluted, and with an absolute path resolved from git rev-parse --show-toplevel rather than a relative one. Working blob back to b540201d = the HEAD blob, git diff HEAD empty. Restored run: 78 passed (78).

The first ablation pass reported 5 red, not 7 — it caught two vacuously-green pins of my own: a for over an absent packages list iterates zero times, and "the output is the default's output plus the list" holds trivially when the list is never added. Both were fixed to assert the addition first (commit a47ef393) before the second pass measured 7.

Verification

Union re-run at final commit a47ef393; the tree was clean for every run below.

• pnpm --filter @objectstack/spec exec vitest run — 450 files, 12068 tests, all passed (exit 0)
• 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)
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (52 commands): 47 exit 0. The other 5 are PREREQUISITE NOT MET / NOT MEASURED, not findings — check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt and check:doc-formula-expressions all want the whole workspace built (66 of 67 packages have no dist/), and check-test-completeness / check-half-states exit 3 by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally; check:api-surface then passed on real declarations (exit 0). CI owns the repo-scale remainder.
• Lint, as a declared narrowing — eslint --no-inline-config --format json over the 3 changed source files: 3 files linted, 0 errors, 0 warnings. The narrowing is a measurement, not a skip: the population is read from eslint's own config (--print-config resolves for each file, exit 0), the count is read from the JSON output, and the invariance holds 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.

Changeset

.changeset/adr0130-composestacks-manifest-preserve.md — @objectstack/spec: minor. A pure widening: the accept set gained exactly one option value, the default is still 'last', no existing value changed meaning, and nothing that parsed before is refused now. The refusal of a neighbouring spelling is pinned alongside the acceptance, so "widened by exactly one" is measured rather than asserted.

Clause-② — yes, and this PR stays draft

Both limbs are hit: the path limb (packages/spec/src/**) and the content limb (a new public option value widens the accept set). needs:contract-review is attached and the PR is draft pending that review.

⚠️ An independent review is required. A verdict rendered by the session that wrote this diff does not satisfy the independence the gate wants — recorded as a process finding on #14191.

The one judgement call a reviewer should look at first: preserve retains the singular manifest (selected by 'last') instead of clearing it. The reasoning is above — additive rather than key-removing, D6's artifact-level identity, and D4's read-both rule making double registration impossible. ADR-0130 does not pin this either way, so it is the decision most worth a second opinion.

⛔ Scope: this ships composition only. The load path that iterates packages in dependency-topological order (D5, through resolvePluginOrder) and the installPackage co-ownership gate (D1/D3) are separate, dependent cards. Composing with 'preserve' today registers no extra package.

Authored in Claude Code session session_01UHvF5hyiZjnCyExFnfQB8m (https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m) — kept in prose because a body edit rewrites the footer's session URL to the bare form.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0185976db0933f220d40f2982ad111f31a2709da — the merge of head a47ef3932791047aacabed1d0386ef6d211fc87a into base 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2, 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 0185976db0933f220d40f2982ad111f31a2709da && git checkout 0185976db0933f220d40f2982ad111f31a2709da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 a47ef3932791047aacabed1d0386ef6d211fc87a && git checkout -B drift-repro 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 && git merge --no-ff a47ef3932791047aacabed1d0386ef6d211fc87a
node scripts/docs-audit/affected-docs.mjs --json 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2

⚠️ 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[hotlong]

CI 全绿；唯一未决项是独立 Clause-② 复审，⛔ 本会话不代劳

a47ef393 上 48 项检查全部完成，无一失败（success 或 skipped）。六个必需上下文按 check-run 名称逐个核对（AGENTS.md §522：必需集按名匹配，改名会静默脱钩，所以按名核而不是按数）：

必需上下文	结论
Lint & Repo Gates	✅ success (14:51:34)
TypeScript Type Check	✅ success
Test Core	✅ success — 汇总 + 6 分片全过
Dogfood Regression Gate	✅ success — 汇总 + 3 分片全过
Build Core	✅ success
Temporal Conformance (live PG + MySQL)	✅ success

Governed Surface Queue Guard 亦 success；Flag docs affected by code changes 的 advisory 已单独核过——两页命中页（getting-started/examples.mdx、glossary.mdx）都没有对 manifest 取值做封闭枚举，'preserve' 叠加后两页逐字仍成立，无文档改动可欠；第三页 content/docs/releases/v17.mdx 是 release-owned，只读不碰。

---

为什么它仍然是 draft，以及我不做什么

⛔ 本 PR 保持 draft，我不 arm auto-merge、不翻 ready。 §522 的前置是"已绿 且已接受 且非 draft"三者齐备；这里只满足第一条。

⛔ Clause-② 的裁决不由本会话作出。 这个 diff 是本会话（session_01UHvF5hyiZjnCyExFnfQB8m）派发并署名的，写 diff 的一方自审不满足该门要求的独立性——这正是 #14191 上记录在案的 process finding，不重蹈。

需要的就一件事：一次独立的 Clause-② 复审。PR 正文已把最该要第二意见的那处判断题标了出来——preserve 保留单数 manifest（按 'last' 选）而非清空它，理由是叠加而非删键、D6 的物级身份、以及 D4 的 read-both 规则使重复注册不可能；ADR-0130 两边都没钉死，所以它是决定性的一处，不是风格问题。

复审通过后即可 ready → 合并队列。在那之前它就该停在这里。

---

Generated by Claude Code

[huangyiirene]

契约复审:PASS —— head a47ef393,同笔清标 + 转 ready + 挂 auto-merge

项目总监席契约复审记录 · session session_01KGtaLpkW1mycWgkbSb3H6t · 档位机读认定在案(claude-fable-5 = CONTRACT_REVIEW_TIER)· 独立性成立(复审会话 ≠ 署名会话 session_01UHvF5hyiZjnCyExFnfQB8m,#14191 的 process finding 得到满足)· 对全 diff 复审(4 文件 +535/−17),⛔ 非对报告。

被点名的判断题,本席审定:保留单数 manifest 正确,维持

PR 正文与车道都把这一处交给第二意见 —— preserve 保留单数 manifest(按 'last' 选)而非清空。三条理由逐一对树核验成立:

1. 无重复注册的机械保证:D4 read-both 规则(feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 落的那条)规定「有 packages ⇒ 走 packages,manifest 是无 packages 时的回退支」—— preserve 输出必带 packages,故其 manifest 永不被当包迭代;
2. D6 物级身份:一件 artifact 一个版本,清空 manifest 反而把 artifact 级身份留空;
3. 加法不删键:读 composed.manifest 的既有消费者看不到键消失。
   ⇒ ADR-0130 未钉的这一处由本复审钉下:preserve = 默认输出 + 包清单,后来者⛔ 不得改为清空式。

条款②与裁决符合性

1. 双肢命中如实申报(spec 路径 + 新公开选项值),draft 候审姿态正确;
2. 恰好加宽一个值,测量而非断言 ✅ —— 邻拼写(preserve-all)与负索引拒绝同钉,默认值 'last' 单独钉(选项 schema parse),default-未动的负半(三个 pick 策略都不铸 packages 键)钉住 —— D7「Reviewer attention is not a mechanism」被照字面执行;
3. read-both 规则单源 ✅ —— preservePackageEntries 应用的是 D4 同一规则(带双备键的 stack 只贡献一次),wrapper 形状以 ArtifactPackageEntrySchema 判而非重declare(ADR-0116 漂移防线),平铺体拒绝作负对照;与 COMPOSE_KEY_DISPOSITIONS 的 'concat' 一致性钉为相等式;
4. feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 留置哨钉的处置正确 ✅ —— 断言未动、只改陈述理由并改题为 BY DEFAULT,哨钉的「让后续变更可见」使命完成而非被删绿;
5. 消融自纠入册 ✅ —— 首轮 5 红暴露两枚自写的空洞钉(零次迭代恒绿、加法未发生时平凡成立),修钉后二轮 7 红恰合预declare —— 这是消融纪律的教科书用法;字节还原证明齐;
6. 单栈短路按身份返回的钉与理由(单 manifest 即 read-both 支 2 的「一个包」)成立;changeset minor 纯加宽定级正确;12068 测试绿,车道已按名核六必需上下文全绿,文档漂移两命中页无封闭枚举、零欠账。

范围内观察(⛔ 不阻落地,记给 D1/D3 实施者):preserve 不去重 —— 两个输入若携带同一 manifest.id,包清单出现重复条目;按 ADR-0130 分工,拒绝重复身份属 installPackage 共有权门(D1/D3)的裁量,组合期不预判。届时该卡请带上这一读数。

收口(同笔)

needs:contract-review 摘除 → draft 转 ready → auto-merge 挂上(合并队列资格 = 全检查绿,已满足)。落地即 Fixes #14164 关卡。

---

Generated by Claude Code

[hotlong]

Fixes#14164

Implements ADR-0130's Consequences follow-up row 3. composeStacks' manifest option accepts a fourth value, 'preserve': instead of keeping one manifest and discarding the rest, it folds every input's package identity into the composed artifact's packages list (ADR-0130 D4), in stack order.

Why a new value rather than a fix to the old ones

manifest: 'first' | 'last' | index is a deliberate pick-one, and it is correct for the case it was written for — several stacks assembled into ONE published package, which has one identity. ADR-0130 introduces the other case: a release artifact that carries N packages, each keeping its own identity, so a product splits into modules without renaming a single object (the object name IS the table name, the REST path, the formula token and the saved-view key, ADR-0129 D1–D2). Composing N stacks under a pick strategy loses N−1 package identities — the lossiness ADR-0130 section 5 rejects composeStacks-as-is for. Both cases are real, so this is an added value, not a change of meaning for the existing ones.

What the mode does

Which entries a stack contributes is D4's read-both rule applied to the inputs — the same rule the load path applies to an artifact, so composition and loading cannot disagree about what "the packages of this stack" means:

• stack declares packages → those entries;
• stack declares no packages → its singular manifest as a single-element list.

A stack carrying both therefore contributes its list once, not its list plus its manifest — nothing is emitted twice in the first place, so there is no de-duplication pass to get wrong later.

Every emitted element is the { manifest: ... } wrapper object, reusing ArtifactPackageEntrySchema (landed by #14191). ⛔ The wrapper shape is not re-derived — a second declaration of one shape is the drift ADR-0116 exists about, and D4 reserved that exact position so a future { ref, integrity } segment stays an additive key rather than a reshape. The pins assert it by feeding composed output to that schema rather than to a literal.

'preserve' is additive over the default, not a fourth pick: the singular manifest is still selected by the same 'last' rule, so a preserve composition's output is the default's output plus the package list. The artifact keeps an artifact-level identity (D6 — one artifact, one version) and no consumer reading composed.manifest sees a key disappear. Nothing is registered twice either: D4's read-both rule reads a packages-carrying artifact through packages, and manifest is the fallback branch for artifacts that have none.

packages' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and keeps its meaning. Preserve composes packages itself and concatenates in stack order too, so the two agree rather than compete — pinned as an equality where every stack carries packages.

The pin #14191 left on purpose — updated, not deleted

#14191 left leaves the singular manifest pick-one semantics alone in packages/spec/src/stack-artifact-packages.test.ts so this follow-up would be a visible change rather than a silent one. It is retitled ... BY DEFAULT, and here is what it now records: its assertions did not move. Preserve is opt-in, the default is still 'last', and a caller passing no options gets what it got before — one manifest kept, and no packages key minted underneath it. Only the pin's stated reason changed, from "until the follow-up lands" to "the follow-up landed and deliberately did not touch this path". ⛔ It was not deleted to make a suite green; the preserve mode's own behaviour is pinned in a separate file.

Reverse verification — red to green

Ablation: if (opts.manifest === 'preserve') { in packages/spec/src/stack.zod.ts replaced by if (false) {, so preserve falls through to the default and builds no list.

• The mutation reached what the test resolves. The pins import ./stack.zod relatively, so vitest resolves package source, not dist — the mutated file is the file under test, and no build stands between them. Confirmed on disk before reading any result, anchored on the text being changed rather than on the editor's exit code: injected-count 1, removed-count 0, and blob b540201d moving to 7bf25448.
• Mutated leg: 7 failed | 71 passed — the preserve pins are red; the 'first' / 'last' / index pins stay green, which is the correct direction (they must be unaffected by the new branch).
• Restore leg, proven by bytes: restored with git checkout HEAD -- FILEPATH — pinned to HEAD rather than the bare form, which reads the index the mutation may have polluted, and with an absolute path resolved from git rev-parse --show-toplevel rather than a relative one. Working blob back to b540201d = the HEAD blob, git diff HEAD empty. Restored run: 78 passed (78).

The first ablation pass reported 5 red, not 7 — it caught two vacuously-green pins of my own: a for over an absent packages list iterates zero times, and "the output is the default's output plus the list" holds trivially when the list is never added. Both were fixed to assert the addition first (commit a47ef393) before the second pass measured 7.

Verification

Union re-run at final commit a47ef393; the tree was clean for every run below.

• pnpm --filter @objectstack/spec exec vitest run — 450 files, 12068 tests, all passed (exit 0)
• 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)
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (52 commands): 47 exit 0. The other 5 are PREREQUISITE NOT MET / NOT MEASURED, not findings — check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt and check:doc-formula-expressions all want the whole workspace built (66 of 67 packages have no dist/), and check-test-completeness / check-half-states exit 3 by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally; check:api-surface then passed on real declarations (exit 0). CI owns the repo-scale remainder.
• Lint, as a declared narrowing — eslint --no-inline-config --format json over the 3 changed source files: 3 files linted, 0 errors, 0 warnings. The narrowing is a measurement, not a skip: the population is read from eslint's own config (--print-config resolves for each file, exit 0), the count is read from the JSON output, and the invariance holds 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.

Changeset

.changeset/adr0130-composestacks-manifest-preserve.md — @objectstack/spec: minor. A pure widening: the accept set gained exactly one option value, the default is still 'last', no existing value changed meaning, and nothing that parsed before is refused now. The refusal of a neighbouring spelling is pinned alongside the acceptance, so "widened by exactly one" is measured rather than asserted.

Clause-② — yes, and this PR stays draft

Both limbs are hit: the path limb (packages/spec/src/**) and the content limb (a new public option value widens the accept set). needs:contract-review is attached and the PR is draft pending that review.

⚠️ An independent review is required. A verdict rendered by the session that wrote this diff does not satisfy the independence the gate wants — recorded as a process finding on #14191.

The one judgement call a reviewer should look at first: preserve retains the singular manifest (selected by 'last') instead of clearing it. The reasoning is above — additive rather than key-removing, D6's artifact-level identity, and D4's read-both rule making double registration impossible. ADR-0130 does not pin this either way, so it is the decision most worth a second opinion.

⛔ Scope: this ships composition only. The load path that iterates packages in dependency-topological order (D5, through resolvePluginOrder) and the installPackage co-ownership gate (D1/D3) are separate, dependent cards. Composing with 'preserve' today registers no extra package.

Authored in Claude Code session session_01UHvF5hyiZjnCyExFnfQB8m (https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m) — kept in prose because a body edit rewrites the footer's session URL to the bare form.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0185976db0933f220d40f2982ad111f31a2709da — the merge of head a47ef3932791047aacabed1d0386ef6d211fc87a into base 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2, 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 0185976db0933f220d40f2982ad111f31a2709da && git checkout 0185976db0933f220d40f2982ad111f31a2709da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 a47ef3932791047aacabed1d0386ef6d211fc87a && git checkout -B drift-repro 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 && git merge --no-ff a47ef3932791047aacabed1d0386ef6d211fc87a
node scripts/docs-audit/affected-docs.mjs --json 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2

⚠️ 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[hotlong]

CI 全绿；唯一未决项是独立 Clause-② 复审，⛔ 本会话不代劳

a47ef393 上 48 项检查全部完成，无一失败（success 或 skipped）。六个必需上下文按 check-run 名称逐个核对（AGENTS.md §522：必需集按名匹配，改名会静默脱钩，所以按名核而不是按数）：

必需上下文	结论
Lint & Repo Gates	✅ success (14:51:34)
TypeScript Type Check	✅ success
Test Core	✅ success — 汇总 + 6 分片全过
Dogfood Regression Gate	✅ success — 汇总 + 3 分片全过
Build Core	✅ success
Temporal Conformance (live PG + MySQL)	✅ success

Governed Surface Queue Guard 亦 success；Flag docs affected by code changes 的 advisory 已单独核过——两页命中页（getting-started/examples.mdx、glossary.mdx）都没有对 manifest 取值做封闭枚举，'preserve' 叠加后两页逐字仍成立，无文档改动可欠；第三页 content/docs/releases/v17.mdx 是 release-owned，只读不碰。

---

为什么它仍然是 draft，以及我不做什么

⛔ 本 PR 保持 draft，我不 arm auto-merge、不翻 ready。 §522 的前置是"已绿 且已接受 且非 draft"三者齐备；这里只满足第一条。

⛔ Clause-② 的裁决不由本会话作出。 这个 diff 是本会话（session_01UHvF5hyiZjnCyExFnfQB8m）派发并署名的，写 diff 的一方自审不满足该门要求的独立性——这正是 #14191 上记录在案的 process finding，不重蹈。

需要的就一件事：一次独立的 Clause-② 复审。PR 正文已把最该要第二意见的那处判断题标了出来——preserve 保留单数 manifest（按 'last' 选）而非清空它，理由是叠加而非删键、D6 的物级身份、以及 D4 的 read-both 规则使重复注册不可能；ADR-0130 两边都没钉死，所以它是决定性的一处，不是风格问题。

复审通过后即可 ready → 合并队列。在那之前它就该停在这里。

---

Generated by Claude Code

[huangyiirene]

契约复审:PASS —— head a47ef393,同笔清标 + 转 ready + 挂 auto-merge

项目总监席契约复审记录 · session session_01KGtaLpkW1mycWgkbSb3H6t · 档位机读认定在案(claude-fable-5 = CONTRACT_REVIEW_TIER)· 独立性成立(复审会话 ≠ 署名会话 session_01UHvF5hyiZjnCyExFnfQB8m,#14191 的 process finding 得到满足)· 对全 diff 复审(4 文件 +535/−17),⛔ 非对报告。

被点名的判断题,本席审定:保留单数 manifest 正确,维持

PR 正文与车道都把这一处交给第二意见 —— preserve 保留单数 manifest(按 'last' 选)而非清空。三条理由逐一对树核验成立:

1. 无重复注册的机械保证:D4 read-both 规则(feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 落的那条)规定「有 packages ⇒ 走 packages,manifest 是无 packages 时的回退支」—— preserve 输出必带 packages,故其 manifest 永不被当包迭代;
2. D6 物级身份:一件 artifact 一个版本,清空 manifest 反而把 artifact 级身份留空;
3. 加法不删键:读 composed.manifest 的既有消费者看不到键消失。
   ⇒ ADR-0130 未钉的这一处由本复审钉下:preserve = 默认输出 + 包清单,后来者⛔ 不得改为清空式。

条款②与裁决符合性

1. 双肢命中如实申报(spec 路径 + 新公开选项值),draft 候审姿态正确;
2. 恰好加宽一个值,测量而非断言 ✅ —— 邻拼写(preserve-all)与负索引拒绝同钉,默认值 'last' 单独钉(选项 schema parse),default-未动的负半(三个 pick 策略都不铸 packages 键)钉住 —— D7「Reviewer attention is not a mechanism」被照字面执行;
3. read-both 规则单源 ✅ —— preservePackageEntries 应用的是 D4 同一规则(带双备键的 stack 只贡献一次),wrapper 形状以 ArtifactPackageEntrySchema 判而非重declare(ADR-0116 漂移防线),平铺体拒绝作负对照;与 COMPOSE_KEY_DISPOSITIONS 的 'concat' 一致性钉为相等式;
4. feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 留置哨钉的处置正确 ✅ —— 断言未动、只改陈述理由并改题为 BY DEFAULT,哨钉的「让后续变更可见」使命完成而非被删绿;
5. 消融自纠入册 ✅ —— 首轮 5 红暴露两枚自写的空洞钉(零次迭代恒绿、加法未发生时平凡成立),修钉后二轮 7 红恰合预declare —— 这是消融纪律的教科书用法;字节还原证明齐;
6. 单栈短路按身份返回的钉与理由(单 manifest 即 read-both 支 2 的「一个包」)成立;changeset minor 纯加宽定级正确;12068 测试绿,车道已按名核六必需上下文全绿,文档漂移两命中页无封闭枚举、零欠账。

范围内观察(⛔ 不阻落地,记给 D1/D3 实施者):preserve 不去重 —— 两个输入若携带同一 manifest.id,包清单出现重复条目;按 ADR-0130 分工,拒绝重复身份属 installPackage 共有权门(D1/D3)的裁量,组合期不预判。届时该卡请带上这一读数。

收口(同笔)

needs:contract-review 摘除 → draft 转 ready → auto-merge 挂上(合并队列资格 = 全检查绿,已满足)。落地即 Fixes #14164 关卡。

---

Generated by Claude Code

[hotlong]

Fixes#14164

Implements ADR-0130's Consequences follow-up row 3. composeStacks' manifest option accepts a fourth value, 'preserve': instead of keeping one manifest and discarding the rest, it folds every input's package identity into the composed artifact's packages list (ADR-0130 D4), in stack order.

Why a new value rather than a fix to the old ones

manifest: 'first' | 'last' | index is a deliberate pick-one, and it is correct for the case it was written for — several stacks assembled into ONE published package, which has one identity. ADR-0130 introduces the other case: a release artifact that carries N packages, each keeping its own identity, so a product splits into modules without renaming a single object (the object name IS the table name, the REST path, the formula token and the saved-view key, ADR-0129 D1–D2). Composing N stacks under a pick strategy loses N−1 package identities — the lossiness ADR-0130 section 5 rejects composeStacks-as-is for. Both cases are real, so this is an added value, not a change of meaning for the existing ones.

What the mode does

Which entries a stack contributes is D4's read-both rule applied to the inputs — the same rule the load path applies to an artifact, so composition and loading cannot disagree about what "the packages of this stack" means:

• stack declares packages → those entries;
• stack declares no packages → its singular manifest as a single-element list.

A stack carrying both therefore contributes its list once, not its list plus its manifest — nothing is emitted twice in the first place, so there is no de-duplication pass to get wrong later.

Every emitted element is the { manifest: ... } wrapper object, reusing ArtifactPackageEntrySchema (landed by #14191). ⛔ The wrapper shape is not re-derived — a second declaration of one shape is the drift ADR-0116 exists about, and D4 reserved that exact position so a future { ref, integrity } segment stays an additive key rather than a reshape. The pins assert it by feeding composed output to that schema rather than to a literal.

'preserve' is additive over the default, not a fourth pick: the singular manifest is still selected by the same 'last' rule, so a preserve composition's output is the default's output plus the package list. The artifact keeps an artifact-level identity (D6 — one artifact, one version) and no consumer reading composed.manifest sees a key disappear. Nothing is registered twice either: D4's read-both rule reads a packages-carrying artifact through packages, and manifest is the fallback branch for artifacts that have none.

packages' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and keeps its meaning. Preserve composes packages itself and concatenates in stack order too, so the two agree rather than compete — pinned as an equality where every stack carries packages.

The pin #14191 left on purpose — updated, not deleted

#14191 left leaves the singular manifest pick-one semantics alone in packages/spec/src/stack-artifact-packages.test.ts so this follow-up would be a visible change rather than a silent one. It is retitled ... BY DEFAULT, and here is what it now records: its assertions did not move. Preserve is opt-in, the default is still 'last', and a caller passing no options gets what it got before — one manifest kept, and no packages key minted underneath it. Only the pin's stated reason changed, from "until the follow-up lands" to "the follow-up landed and deliberately did not touch this path". ⛔ It was not deleted to make a suite green; the preserve mode's own behaviour is pinned in a separate file.

Reverse verification — red to green

Ablation: if (opts.manifest === 'preserve') { in packages/spec/src/stack.zod.ts replaced by if (false) {, so preserve falls through to the default and builds no list.

• The mutation reached what the test resolves. The pins import ./stack.zod relatively, so vitest resolves package source, not dist — the mutated file is the file under test, and no build stands between them. Confirmed on disk before reading any result, anchored on the text being changed rather than on the editor's exit code: injected-count 1, removed-count 0, and blob b540201d moving to 7bf25448.
• Mutated leg: 7 failed | 71 passed — the preserve pins are red; the 'first' / 'last' / index pins stay green, which is the correct direction (they must be unaffected by the new branch).
• Restore leg, proven by bytes: restored with git checkout HEAD -- FILEPATH — pinned to HEAD rather than the bare form, which reads the index the mutation may have polluted, and with an absolute path resolved from git rev-parse --show-toplevel rather than a relative one. Working blob back to b540201d = the HEAD blob, git diff HEAD empty. Restored run: 78 passed (78).

The first ablation pass reported 5 red, not 7 — it caught two vacuously-green pins of my own: a for over an absent packages list iterates zero times, and "the output is the default's output plus the list" holds trivially when the list is never added. Both were fixed to assert the addition first (commit a47ef393) before the second pass measured 7.

Verification

Union re-run at final commit a47ef393; the tree was clean for every run below.

• pnpm --filter @objectstack/spec exec vitest run — 450 files, 12068 tests, all passed (exit 0)
• 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)
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (52 commands): 47 exit 0. The other 5 are PREREQUISITE NOT MET / NOT MEASURED, not findings — check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt and check:doc-formula-expressions all want the whole workspace built (66 of 67 packages have no dist/), and check-test-completeness / check-half-states exit 3 by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally; check:api-surface then passed on real declarations (exit 0). CI owns the repo-scale remainder.
• Lint, as a declared narrowing — eslint --no-inline-config --format json over the 3 changed source files: 3 files linted, 0 errors, 0 warnings. The narrowing is a measurement, not a skip: the population is read from eslint's own config (--print-config resolves for each file, exit 0), the count is read from the JSON output, and the invariance holds 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.

Changeset

.changeset/adr0130-composestacks-manifest-preserve.md — @objectstack/spec: minor. A pure widening: the accept set gained exactly one option value, the default is still 'last', no existing value changed meaning, and nothing that parsed before is refused now. The refusal of a neighbouring spelling is pinned alongside the acceptance, so "widened by exactly one" is measured rather than asserted.

Clause-② — yes, and this PR stays draft

Both limbs are hit: the path limb (packages/spec/src/**) and the content limb (a new public option value widens the accept set). needs:contract-review is attached and the PR is draft pending that review.

⚠️ An independent review is required. A verdict rendered by the session that wrote this diff does not satisfy the independence the gate wants — recorded as a process finding on #14191.

The one judgement call a reviewer should look at first: preserve retains the singular manifest (selected by 'last') instead of clearing it. The reasoning is above — additive rather than key-removing, D6's artifact-level identity, and D4's read-both rule making double registration impossible. ADR-0130 does not pin this either way, so it is the decision most worth a second opinion.

⛔ Scope: this ships composition only. The load path that iterates packages in dependency-topological order (D5, through resolvePluginOrder) and the installPackage co-ownership gate (D1/D3) are separate, dependent cards. Composing with 'preserve' today registers no extra package.

Authored in Claude Code session session_01UHvF5hyiZjnCyExFnfQB8m (https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m) — kept in prose because a body edit rewrites the footer's session URL to the bare form.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0185976db0933f220d40f2982ad111f31a2709da — the merge of head a47ef3932791047aacabed1d0386ef6d211fc87a into base 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2, 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 0185976db0933f220d40f2982ad111f31a2709da && git checkout 0185976db0933f220d40f2982ad111f31a2709da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 a47ef3932791047aacabed1d0386ef6d211fc87a && git checkout -B drift-repro 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 && git merge --no-ff a47ef3932791047aacabed1d0386ef6d211fc87a
node scripts/docs-audit/affected-docs.mjs --json 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2

⚠️ 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[hotlong]

CI 全绿；唯一未决项是独立 Clause-② 复审，⛔ 本会话不代劳

a47ef393 上 48 项检查全部完成，无一失败（success 或 skipped）。六个必需上下文按 check-run 名称逐个核对（AGENTS.md §522：必需集按名匹配，改名会静默脱钩，所以按名核而不是按数）：

必需上下文	结论
Lint & Repo Gates	✅ success (14:51:34)
TypeScript Type Check	✅ success
Test Core	✅ success — 汇总 + 6 分片全过
Dogfood Regression Gate	✅ success — 汇总 + 3 分片全过
Build Core	✅ success
Temporal Conformance (live PG + MySQL)	✅ success

Governed Surface Queue Guard 亦 success；Flag docs affected by code changes 的 advisory 已单独核过——两页命中页（getting-started/examples.mdx、glossary.mdx）都没有对 manifest 取值做封闭枚举，'preserve' 叠加后两页逐字仍成立，无文档改动可欠；第三页 content/docs/releases/v17.mdx 是 release-owned，只读不碰。

---

为什么它仍然是 draft，以及我不做什么

⛔ 本 PR 保持 draft，我不 arm auto-merge、不翻 ready。 §522 的前置是"已绿 且已接受 且非 draft"三者齐备；这里只满足第一条。

⛔ Clause-② 的裁决不由本会话作出。 这个 diff 是本会话（session_01UHvF5hyiZjnCyExFnfQB8m）派发并署名的，写 diff 的一方自审不满足该门要求的独立性——这正是 #14191 上记录在案的 process finding，不重蹈。

需要的就一件事：一次独立的 Clause-② 复审。PR 正文已把最该要第二意见的那处判断题标了出来——preserve 保留单数 manifest（按 'last' 选）而非清空它，理由是叠加而非删键、D6 的物级身份、以及 D4 的 read-both 规则使重复注册不可能；ADR-0130 两边都没钉死，所以它是决定性的一处，不是风格问题。

复审通过后即可 ready → 合并队列。在那之前它就该停在这里。

---

Generated by Claude Code

[huangyiirene]

契约复审:PASS —— head a47ef393,同笔清标 + 转 ready + 挂 auto-merge

项目总监席契约复审记录 · session session_01KGtaLpkW1mycWgkbSb3H6t · 档位机读认定在案(claude-fable-5 = CONTRACT_REVIEW_TIER)· 独立性成立(复审会话 ≠ 署名会话 session_01UHvF5hyiZjnCyExFnfQB8m,#14191 的 process finding 得到满足)· 对全 diff 复审(4 文件 +535/−17),⛔ 非对报告。

被点名的判断题,本席审定:保留单数 manifest 正确,维持

PR 正文与车道都把这一处交给第二意见 —— preserve 保留单数 manifest(按 'last' 选)而非清空。三条理由逐一对树核验成立:

1. 无重复注册的机械保证:D4 read-both 规则(feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 落的那条)规定「有 packages ⇒ 走 packages,manifest 是无 packages 时的回退支」—— preserve 输出必带 packages,故其 manifest 永不被当包迭代;
2. D6 物级身份:一件 artifact 一个版本,清空 manifest 反而把 artifact 级身份留空;
3. 加法不删键:读 composed.manifest 的既有消费者看不到键消失。
   ⇒ ADR-0130 未钉的这一处由本复审钉下:preserve = 默认输出 + 包清单,后来者⛔ 不得改为清空式。

条款②与裁决符合性

1. 双肢命中如实申报(spec 路径 + 新公开选项值),draft 候审姿态正确;
2. 恰好加宽一个值,测量而非断言 ✅ —— 邻拼写(preserve-all)与负索引拒绝同钉,默认值 'last' 单独钉(选项 schema parse),default-未动的负半(三个 pick 策略都不铸 packages 键)钉住 —— D7「Reviewer attention is not a mechanism」被照字面执行;
3. read-both 规则单源 ✅ —— preservePackageEntries 应用的是 D4 同一规则(带双备键的 stack 只贡献一次),wrapper 形状以 ArtifactPackageEntrySchema 判而非重declare(ADR-0116 漂移防线),平铺体拒绝作负对照;与 COMPOSE_KEY_DISPOSITIONS 的 'concat' 一致性钉为相等式;
4. feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 留置哨钉的处置正确 ✅ —— 断言未动、只改陈述理由并改题为 BY DEFAULT,哨钉的「让后续变更可见」使命完成而非被删绿;
5. 消融自纠入册 ✅ —— 首轮 5 红暴露两枚自写的空洞钉(零次迭代恒绿、加法未发生时平凡成立),修钉后二轮 7 红恰合预declare —— 这是消融纪律的教科书用法;字节还原证明齐;
6. 单栈短路按身份返回的钉与理由(单 manifest 即 read-both 支 2 的「一个包」)成立;changeset minor 纯加宽定级正确;12068 测试绿,车道已按名核六必需上下文全绿,文档漂移两命中页无封闭枚举、零欠账。

范围内观察(⛔ 不阻落地,记给 D1/D3 实施者):preserve 不去重 —— 两个输入若携带同一 manifest.id,包清单出现重复条目;按 ADR-0130 分工,拒绝重复身份属 installPackage 共有权门(D1/D3)的裁量,组合期不预判。届时该卡请带上这一读数。

收口(同笔)

needs:contract-review 摘除 → draft 转 ready → auto-merge 挂上(合并队列资格 = 全检查绿,已满足)。落地即 Fixes #14164 关卡。

---

Generated by Claude Code

[hotlong]

Fixes#14164

Implements ADR-0130's Consequences follow-up row 3. composeStacks' manifest option accepts a fourth value, 'preserve': instead of keeping one manifest and discarding the rest, it folds every input's package identity into the composed artifact's packages list (ADR-0130 D4), in stack order.

Why a new value rather than a fix to the old ones

manifest: 'first' | 'last' | index is a deliberate pick-one, and it is correct for the case it was written for — several stacks assembled into ONE published package, which has one identity. ADR-0130 introduces the other case: a release artifact that carries N packages, each keeping its own identity, so a product splits into modules without renaming a single object (the object name IS the table name, the REST path, the formula token and the saved-view key, ADR-0129 D1–D2). Composing N stacks under a pick strategy loses N−1 package identities — the lossiness ADR-0130 section 5 rejects composeStacks-as-is for. Both cases are real, so this is an added value, not a change of meaning for the existing ones.

What the mode does

Which entries a stack contributes is D4's read-both rule applied to the inputs — the same rule the load path applies to an artifact, so composition and loading cannot disagree about what "the packages of this stack" means:

• stack declares packages → those entries;
• stack declares no packages → its singular manifest as a single-element list.

A stack carrying both therefore contributes its list once, not its list plus its manifest — nothing is emitted twice in the first place, so there is no de-duplication pass to get wrong later.

Every emitted element is the { manifest: ... } wrapper object, reusing ArtifactPackageEntrySchema (landed by #14191). ⛔ The wrapper shape is not re-derived — a second declaration of one shape is the drift ADR-0116 exists about, and D4 reserved that exact position so a future { ref, integrity } segment stays an additive key rather than a reshape. The pins assert it by feeding composed output to that schema rather than to a literal.

'preserve' is additive over the default, not a fourth pick: the singular manifest is still selected by the same 'last' rule, so a preserve composition's output is the default's output plus the package list. The artifact keeps an artifact-level identity (D6 — one artifact, one version) and no consumer reading composed.manifest sees a key disappear. Nothing is registered twice either: D4's read-both rule reads a packages-carrying artifact through packages, and manifest is the fallback branch for artifacts that have none.

packages' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and keeps its meaning. Preserve composes packages itself and concatenates in stack order too, so the two agree rather than compete — pinned as an equality where every stack carries packages.

The pin #14191 left on purpose — updated, not deleted

#14191 left leaves the singular manifest pick-one semantics alone in packages/spec/src/stack-artifact-packages.test.ts so this follow-up would be a visible change rather than a silent one. It is retitled ... BY DEFAULT, and here is what it now records: its assertions did not move. Preserve is opt-in, the default is still 'last', and a caller passing no options gets what it got before — one manifest kept, and no packages key minted underneath it. Only the pin's stated reason changed, from "until the follow-up lands" to "the follow-up landed and deliberately did not touch this path". ⛔ It was not deleted to make a suite green; the preserve mode's own behaviour is pinned in a separate file.

Reverse verification — red to green

Ablation: if (opts.manifest === 'preserve') { in packages/spec/src/stack.zod.ts replaced by if (false) {, so preserve falls through to the default and builds no list.

• The mutation reached what the test resolves. The pins import ./stack.zod relatively, so vitest resolves package source, not dist — the mutated file is the file under test, and no build stands between them. Confirmed on disk before reading any result, anchored on the text being changed rather than on the editor's exit code: injected-count 1, removed-count 0, and blob b540201d moving to 7bf25448.
• Mutated leg: 7 failed | 71 passed — the preserve pins are red; the 'first' / 'last' / index pins stay green, which is the correct direction (they must be unaffected by the new branch).
• Restore leg, proven by bytes: restored with git checkout HEAD -- FILEPATH — pinned to HEAD rather than the bare form, which reads the index the mutation may have polluted, and with an absolute path resolved from git rev-parse --show-toplevel rather than a relative one. Working blob back to b540201d = the HEAD blob, git diff HEAD empty. Restored run: 78 passed (78).

The first ablation pass reported 5 red, not 7 — it caught two vacuously-green pins of my own: a for over an absent packages list iterates zero times, and "the output is the default's output plus the list" holds trivially when the list is never added. Both were fixed to assert the addition first (commit a47ef393) before the second pass measured 7.

Verification

Union re-run at final commit a47ef393; the tree was clean for every run below.

• pnpm --filter @objectstack/spec exec vitest run — 450 files, 12068 tests, all passed (exit 0)
• 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)
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (52 commands): 47 exit 0. The other 5 are PREREQUISITE NOT MET / NOT MEASURED, not findings — check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt and check:doc-formula-expressions all want the whole workspace built (66 of 67 packages have no dist/), and check-test-completeness / check-half-states exit 3 by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally; check:api-surface then passed on real declarations (exit 0). CI owns the repo-scale remainder.
• Lint, as a declared narrowing — eslint --no-inline-config --format json over the 3 changed source files: 3 files linted, 0 errors, 0 warnings. The narrowing is a measurement, not a skip: the population is read from eslint's own config (--print-config resolves for each file, exit 0), the count is read from the JSON output, and the invariance holds 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.

Changeset

.changeset/adr0130-composestacks-manifest-preserve.md — @objectstack/spec: minor. A pure widening: the accept set gained exactly one option value, the default is still 'last', no existing value changed meaning, and nothing that parsed before is refused now. The refusal of a neighbouring spelling is pinned alongside the acceptance, so "widened by exactly one" is measured rather than asserted.

Clause-② — yes, and this PR stays draft

Both limbs are hit: the path limb (packages/spec/src/**) and the content limb (a new public option value widens the accept set). needs:contract-review is attached and the PR is draft pending that review.

⚠️ An independent review is required. A verdict rendered by the session that wrote this diff does not satisfy the independence the gate wants — recorded as a process finding on #14191.

The one judgement call a reviewer should look at first: preserve retains the singular manifest (selected by 'last') instead of clearing it. The reasoning is above — additive rather than key-removing, D6's artifact-level identity, and D4's read-both rule making double registration impossible. ADR-0130 does not pin this either way, so it is the decision most worth a second opinion.

⛔ Scope: this ships composition only. The load path that iterates packages in dependency-topological order (D5, through resolvePluginOrder) and the installPackage co-ownership gate (D1/D3) are separate, dependent cards. Composing with 'preserve' today registers no extra package.

Authored in Claude Code session session_01UHvF5hyiZjnCyExFnfQB8m (https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m) — kept in prose because a body edit rewrites the footer's session URL to the bare form.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0185976db0933f220d40f2982ad111f31a2709da — the merge of head a47ef3932791047aacabed1d0386ef6d211fc87a into base 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2, 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 0185976db0933f220d40f2982ad111f31a2709da && git checkout 0185976db0933f220d40f2982ad111f31a2709da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 a47ef3932791047aacabed1d0386ef6d211fc87a && git checkout -B drift-repro 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 && git merge --no-ff a47ef3932791047aacabed1d0386ef6d211fc87a
node scripts/docs-audit/affected-docs.mjs --json 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2

⚠️ 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[hotlong]

CI 全绿；唯一未决项是独立 Clause-② 复审，⛔ 本会话不代劳

a47ef393 上 48 项检查全部完成，无一失败（success 或 skipped）。六个必需上下文按 check-run 名称逐个核对（AGENTS.md §522：必需集按名匹配，改名会静默脱钩，所以按名核而不是按数）：

必需上下文	结论
Lint & Repo Gates	✅ success (14:51:34)
TypeScript Type Check	✅ success
Test Core	✅ success — 汇总 + 6 分片全过
Dogfood Regression Gate	✅ success — 汇总 + 3 分片全过
Build Core	✅ success
Temporal Conformance (live PG + MySQL)	✅ success

Governed Surface Queue Guard 亦 success；Flag docs affected by code changes 的 advisory 已单独核过——两页命中页（getting-started/examples.mdx、glossary.mdx）都没有对 manifest 取值做封闭枚举，'preserve' 叠加后两页逐字仍成立，无文档改动可欠；第三页 content/docs/releases/v17.mdx 是 release-owned，只读不碰。

---

为什么它仍然是 draft，以及我不做什么

⛔ 本 PR 保持 draft，我不 arm auto-merge、不翻 ready。 §522 的前置是"已绿 且已接受 且非 draft"三者齐备；这里只满足第一条。

⛔ Clause-② 的裁决不由本会话作出。 这个 diff 是本会话（session_01UHvF5hyiZjnCyExFnfQB8m）派发并署名的，写 diff 的一方自审不满足该门要求的独立性——这正是 #14191 上记录在案的 process finding，不重蹈。

需要的就一件事：一次独立的 Clause-② 复审。PR 正文已把最该要第二意见的那处判断题标了出来——preserve 保留单数 manifest（按 'last' 选）而非清空它，理由是叠加而非删键、D6 的物级身份、以及 D4 的 read-both 规则使重复注册不可能；ADR-0130 两边都没钉死，所以它是决定性的一处，不是风格问题。

复审通过后即可 ready → 合并队列。在那之前它就该停在这里。

---

Generated by Claude Code

[huangyiirene]

契约复审:PASS —— head a47ef393,同笔清标 + 转 ready + 挂 auto-merge

项目总监席契约复审记录 · session session_01KGtaLpkW1mycWgkbSb3H6t · 档位机读认定在案(claude-fable-5 = CONTRACT_REVIEW_TIER)· 独立性成立(复审会话 ≠ 署名会话 session_01UHvF5hyiZjnCyExFnfQB8m,#14191 的 process finding 得到满足)· 对全 diff 复审(4 文件 +535/−17),⛔ 非对报告。

被点名的判断题,本席审定:保留单数 manifest 正确,维持

PR 正文与车道都把这一处交给第二意见 —— preserve 保留单数 manifest(按 'last' 选)而非清空。三条理由逐一对树核验成立:

1. 无重复注册的机械保证:D4 read-both 规则(feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 落的那条)规定「有 packages ⇒ 走 packages,manifest 是无 packages 时的回退支」—— preserve 输出必带 packages,故其 manifest 永不被当包迭代;
2. D6 物级身份:一件 artifact 一个版本,清空 manifest 反而把 artifact 级身份留空;
3. 加法不删键:读 composed.manifest 的既有消费者看不到键消失。
   ⇒ ADR-0130 未钉的这一处由本复审钉下:preserve = 默认输出 + 包清单,后来者⛔ 不得改为清空式。

条款②与裁决符合性

1. 双肢命中如实申报(spec 路径 + 新公开选项值),draft 候审姿态正确;
2. 恰好加宽一个值,测量而非断言 ✅ —— 邻拼写(preserve-all)与负索引拒绝同钉,默认值 'last' 单独钉(选项 schema parse),default-未动的负半(三个 pick 策略都不铸 packages 键)钉住 —— D7「Reviewer attention is not a mechanism」被照字面执行;
3. read-both 规则单源 ✅ —— preservePackageEntries 应用的是 D4 同一规则(带双备键的 stack 只贡献一次),wrapper 形状以 ArtifactPackageEntrySchema 判而非重declare(ADR-0116 漂移防线),平铺体拒绝作负对照;与 COMPOSE_KEY_DISPOSITIONS 的 'concat' 一致性钉为相等式;
4. feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 留置哨钉的处置正确 ✅ —— 断言未动、只改陈述理由并改题为 BY DEFAULT,哨钉的「让后续变更可见」使命完成而非被删绿;
5. 消融自纠入册 ✅ —— 首轮 5 红暴露两枚自写的空洞钉(零次迭代恒绿、加法未发生时平凡成立),修钉后二轮 7 红恰合预declare —— 这是消融纪律的教科书用法;字节还原证明齐;
6. 单栈短路按身份返回的钉与理由(单 manifest 即 read-both 支 2 的「一个包」)成立;changeset minor 纯加宽定级正确;12068 测试绿,车道已按名核六必需上下文全绿,文档漂移两命中页无封闭枚举、零欠账。

范围内观察(⛔ 不阻落地,记给 D1/D3 实施者):preserve 不去重 —— 两个输入若携带同一 manifest.id,包清单出现重复条目;按 ADR-0130 分工,拒绝重复身份属 installPackage 共有权门(D1/D3)的裁量,组合期不预判。届时该卡请带上这一读数。

收口(同笔)

needs:contract-review 摘除 → draft 转 ready → auto-merge 挂上(合并队列资格 = 全检查绿,已满足)。落地即 Fixes #14164 关卡。

---

Generated by Claude Code

[hotlong]

Fixes#14164

Implements ADR-0130's Consequences follow-up row 3. composeStacks' manifest option accepts a fourth value, 'preserve': instead of keeping one manifest and discarding the rest, it folds every input's package identity into the composed artifact's packages list (ADR-0130 D4), in stack order.

Why a new value rather than a fix to the old ones

manifest: 'first' | 'last' | index is a deliberate pick-one, and it is correct for the case it was written for — several stacks assembled into ONE published package, which has one identity. ADR-0130 introduces the other case: a release artifact that carries N packages, each keeping its own identity, so a product splits into modules without renaming a single object (the object name IS the table name, the REST path, the formula token and the saved-view key, ADR-0129 D1–D2). Composing N stacks under a pick strategy loses N−1 package identities — the lossiness ADR-0130 section 5 rejects composeStacks-as-is for. Both cases are real, so this is an added value, not a change of meaning for the existing ones.

What the mode does

Which entries a stack contributes is D4's read-both rule applied to the inputs — the same rule the load path applies to an artifact, so composition and loading cannot disagree about what "the packages of this stack" means:

• stack declares packages → those entries;
• stack declares no packages → its singular manifest as a single-element list.

A stack carrying both therefore contributes its list once, not its list plus its manifest — nothing is emitted twice in the first place, so there is no de-duplication pass to get wrong later.

Every emitted element is the { manifest: ... } wrapper object, reusing ArtifactPackageEntrySchema (landed by #14191). ⛔ The wrapper shape is not re-derived — a second declaration of one shape is the drift ADR-0116 exists about, and D4 reserved that exact position so a future { ref, integrity } segment stays an additive key rather than a reshape. The pins assert it by feeding composed output to that schema rather than to a literal.

'preserve' is additive over the default, not a fourth pick: the singular manifest is still selected by the same 'last' rule, so a preserve composition's output is the default's output plus the package list. The artifact keeps an artifact-level identity (D6 — one artifact, one version) and no consumer reading composed.manifest sees a key disappear. Nothing is registered twice either: D4's read-both rule reads a packages-carrying artifact through packages, and manifest is the fallback branch for artifacts that have none.

packages' declared COMPOSE_KEY_DISPOSITIONS entry stays 'concat' and keeps its meaning. Preserve composes packages itself and concatenates in stack order too, so the two agree rather than compete — pinned as an equality where every stack carries packages.

The pin #14191 left on purpose — updated, not deleted

#14191 left leaves the singular manifest pick-one semantics alone in packages/spec/src/stack-artifact-packages.test.ts so this follow-up would be a visible change rather than a silent one. It is retitled ... BY DEFAULT, and here is what it now records: its assertions did not move. Preserve is opt-in, the default is still 'last', and a caller passing no options gets what it got before — one manifest kept, and no packages key minted underneath it. Only the pin's stated reason changed, from "until the follow-up lands" to "the follow-up landed and deliberately did not touch this path". ⛔ It was not deleted to make a suite green; the preserve mode's own behaviour is pinned in a separate file.

Reverse verification — red to green

Ablation: if (opts.manifest === 'preserve') { in packages/spec/src/stack.zod.ts replaced by if (false) {, so preserve falls through to the default and builds no list.

• The mutation reached what the test resolves. The pins import ./stack.zod relatively, so vitest resolves package source, not dist — the mutated file is the file under test, and no build stands between them. Confirmed on disk before reading any result, anchored on the text being changed rather than on the editor's exit code: injected-count 1, removed-count 0, and blob b540201d moving to 7bf25448.
• Mutated leg: 7 failed | 71 passed — the preserve pins are red; the 'first' / 'last' / index pins stay green, which is the correct direction (they must be unaffected by the new branch).
• Restore leg, proven by bytes: restored with git checkout HEAD -- FILEPATH — pinned to HEAD rather than the bare form, which reads the index the mutation may have polluted, and with an absolute path resolved from git rev-parse --show-toplevel rather than a relative one. Working blob back to b540201d = the HEAD blob, git diff HEAD empty. Restored run: 78 passed (78).

The first ablation pass reported 5 red, not 7 — it caught two vacuously-green pins of my own: a for over an absent packages list iterates zero times, and "the output is the default's output plus the list" holds trivially when the list is never added. Both were fixed to assert the addition first (commit a47ef393) before the second pass measured 7.

Verification

Union re-run at final commit a47ef393; the tree was clean for every run below.

• pnpm --filter @objectstack/spec exec vitest run — 450 files, 12068 tests, all passed (exit 0)
• 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)
• Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (52 commands): 47 exit 0. The other 5 are PREREQUISITE NOT MET / NOT MEASURED, not findings — check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-debt and check:doc-formula-expressions all want the whole workspace built (66 of 67 packages have no dist/), and check-test-completeness / check-half-states exit 3 by design outside CI. @objectstack/spec and @objectstack/formula were built to clear that class as far as it goes locally; check:api-surface then passed on real declarations (exit 0). CI owns the repo-scale remainder.
• Lint, as a declared narrowing — eslint --no-inline-config --format json over the 3 changed source files: 3 files linted, 0 errors, 0 warnings. The narrowing is a measurement, not a skip: the population is read from eslint's own config (--print-config resolves for each file, exit 0), the count is read from the JSON output, and the invariance holds 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.

Changeset

.changeset/adr0130-composestacks-manifest-preserve.md — @objectstack/spec: minor. A pure widening: the accept set gained exactly one option value, the default is still 'last', no existing value changed meaning, and nothing that parsed before is refused now. The refusal of a neighbouring spelling is pinned alongside the acceptance, so "widened by exactly one" is measured rather than asserted.

Clause-② — yes, and this PR stays draft

Both limbs are hit: the path limb (packages/spec/src/**) and the content limb (a new public option value widens the accept set). needs:contract-review is attached and the PR is draft pending that review.

⚠️ An independent review is required. A verdict rendered by the session that wrote this diff does not satisfy the independence the gate wants — recorded as a process finding on #14191.

The one judgement call a reviewer should look at first: preserve retains the singular manifest (selected by 'last') instead of clearing it. The reasoning is above — additive rather than key-removing, D6's artifact-level identity, and D4's read-both rule making double registration impossible. ADR-0130 does not pin this either way, so it is the decision most worth a second opinion.

⛔ Scope: this ships composition only. The load path that iterates packages in dependency-topological order (D5, through resolvePluginOrder) and the installPackage co-ownership gate (D1/D3) are separate, dependent cards. Composing with 'preserve' today registers no extra package.

Authored in Claude Code session session_01UHvF5hyiZjnCyExFnfQB8m (https://claude.ai/code/session_01UHvF5hyiZjnCyExFnfQB8m) — kept in prose because a body edit rewrites the footer's session URL to the bare form.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0185976db0933f220d40f2982ad111f31a2709da — the merge of head a47ef3932791047aacabed1d0386ef6d211fc87a into base 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2, 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 0185976db0933f220d40f2982ad111f31a2709da && git checkout 0185976db0933f220d40f2982ad111f31a2709da
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 a47ef3932791047aacabed1d0386ef6d211fc87a && git checkout -B drift-repro 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 && git merge --no-ff a47ef3932791047aacabed1d0386ef6d211fc87a
node scripts/docs-audit/affected-docs.mjs --json 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2

⚠️ 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 33dea61f579288c6f1b6b7e9a4789b932ddfa3e2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[hotlong]

CI 全绿；唯一未决项是独立 Clause-② 复审，⛔ 本会话不代劳

a47ef393 上 48 项检查全部完成，无一失败（success 或 skipped）。六个必需上下文按 check-run 名称逐个核对（AGENTS.md §522：必需集按名匹配，改名会静默脱钩，所以按名核而不是按数）：

必需上下文	结论
Lint & Repo Gates	✅ success (14:51:34)
TypeScript Type Check	✅ success
Test Core	✅ success — 汇总 + 6 分片全过
Dogfood Regression Gate	✅ success — 汇总 + 3 分片全过
Build Core	✅ success
Temporal Conformance (live PG + MySQL)	✅ success

Governed Surface Queue Guard 亦 success；Flag docs affected by code changes 的 advisory 已单独核过——两页命中页（getting-started/examples.mdx、glossary.mdx）都没有对 manifest 取值做封闭枚举，'preserve' 叠加后两页逐字仍成立，无文档改动可欠；第三页 content/docs/releases/v17.mdx 是 release-owned，只读不碰。

---

为什么它仍然是 draft，以及我不做什么

⛔ 本 PR 保持 draft，我不 arm auto-merge、不翻 ready。 §522 的前置是"已绿 且已接受 且非 draft"三者齐备；这里只满足第一条。

⛔ Clause-② 的裁决不由本会话作出。 这个 diff 是本会话（session_01UHvF5hyiZjnCyExFnfQB8m）派发并署名的，写 diff 的一方自审不满足该门要求的独立性——这正是 #14191 上记录在案的 process finding，不重蹈。

需要的就一件事：一次独立的 Clause-② 复审。PR 正文已把最该要第二意见的那处判断题标了出来——preserve 保留单数 manifest（按 'last' 选）而非清空它，理由是叠加而非删键、D6 的物级身份、以及 D4 的 read-both 规则使重复注册不可能；ADR-0130 两边都没钉死，所以它是决定性的一处，不是风格问题。

复审通过后即可 ready → 合并队列。在那之前它就该停在这里。

---

Generated by Claude Code

[huangyiirene]

契约复审:PASS —— head a47ef393,同笔清标 + 转 ready + 挂 auto-merge

项目总监席契约复审记录 · session session_01KGtaLpkW1mycWgkbSb3H6t · 档位机读认定在案(claude-fable-5 = CONTRACT_REVIEW_TIER)· 独立性成立(复审会话 ≠ 署名会话 session_01UHvF5hyiZjnCyExFnfQB8m,#14191 的 process finding 得到满足)· 对全 diff 复审(4 文件 +535/−17),⛔ 非对报告。

被点名的判断题,本席审定:保留单数 manifest 正确,维持

PR 正文与车道都把这一处交给第二意见 —— preserve 保留单数 manifest(按 'last' 选)而非清空。三条理由逐一对树核验成立:

1. 无重复注册的机械保证:D4 read-both 规则(feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 落的那条)规定「有 packages ⇒ 走 packages,manifest 是无 packages 时的回退支」—— preserve 输出必带 packages,故其 manifest 永不被当包迭代;
2. D6 物级身份:一件 artifact 一个版本,清空 manifest 反而把 artifact 级身份留空;
3. 加法不删键:读 composed.manifest 的既有消费者看不到键消失。
   ⇒ ADR-0130 未钉的这一处由本复审钉下:preserve = 默认输出 + 包清单,后来者⛔ 不得改为清空式。

条款②与裁决符合性

1. 双肢命中如实申报(spec 路径 + 新公开选项值),draft 候审姿态正确;
2. 恰好加宽一个值,测量而非断言 ✅ —— 邻拼写(preserve-all)与负索引拒绝同钉,默认值 'last' 单独钉(选项 schema parse),default-未动的负半(三个 pick 策略都不铸 packages 键)钉住 —— D7「Reviewer attention is not a mechanism」被照字面执行;
3. read-both 规则单源 ✅ —— preservePackageEntries 应用的是 D4 同一规则(带双备键的 stack 只贡献一次),wrapper 形状以 ArtifactPackageEntrySchema 判而非重declare(ADR-0116 漂移防线),平铺体拒绝作负对照;与 COMPOSE_KEY_DISPOSITIONS 的 'concat' 一致性钉为相等式;
4. feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191 留置哨钉的处置正确 ✅ —— 断言未动、只改陈述理由并改题为 BY DEFAULT,哨钉的「让后续变更可见」使命完成而非被删绿;
5. 消融自纠入册 ✅ —— 首轮 5 红暴露两枚自写的空洞钉(零次迭代恒绿、加法未发生时平凡成立),修钉后二轮 7 红恰合预declare —— 这是消融纪律的教科书用法;字节还原证明齐;
6. 单栈短路按身份返回的钉与理由(单 manifest 即 read-both 支 2 的「一个包」)成立;changeset minor 纯加宽定级正确;12068 测试绿,车道已按名核六必需上下文全绿,文档漂移两命中页无封闭枚举、零欠账。

范围内观察(⛔ 不阻落地,记给 D1/D3 实施者):preserve 不去重 —— 两个输入若携带同一 manifest.id,包清单出现重复条目;按 ADR-0130 分工,拒绝重复身份属 installPackage 共有权门(D1/D3)的裁量,组合期不预判。届时该卡请带上这一读数。

收口(同笔)

needs:contract-review 摘除 → draft 转 ready → auto-merge 挂上(合并队列资格 = 全检查绿,已满足)。落地即 Fixes #14164 关卡。

---

Generated by Claude Code