feat(cli+spec): 从 N 个软件包的作者态编出一个 `packages[]` 发布物 —— `os build` 认识项目级 `composeStacks('preserve')`，装配后的包体有自己的声明（#14242 取 B）

[hotlong]

Part of #14122 · ADR-0130 D4/D5/D7 的产出侧。发版前平台侧最后一块：维护者要在平台功能齐全后发版，hotcrm 分拆（epic 的业务目标）在本卡之前无法开始。

事实（都在 main 上实测）

• 装载链已齐：feat(spec): the release artifact may carry N package manifests — optional packages[] (ADR-0130 D4) #14191（packages[] schema）、feat(spec): composeStacks gains manifest: 'preserve' — N package identities survive composition (ADR-0130 row 3) #14223（composeStacks manifest:'preserve'）、ADR-0130 D5+D7: register an artifact's N packages in topological order, reusing resolvePluginOrder #14240（拓扑装载）、feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3) #14354（D1+D3 闸）都在 main。
• 但没有任何路径能编出 packages[] 形态的发布物：packages/cli/src/commands/compile.ts（build.ts 只是它的别名）对 artifact.packages 零处理（git grep '\.packages\b' packages/cli/src packages/core/src 非测试零命中）；examples/ 下四个例子全是单包；ArtifactPackageEntrySchema's body half cannot describe the payload the load path actually registers #14242 原文："No packages[]-shaped artifact is produced anywhere yet"。
• 作者态是什么样：hotcrm objectstack.config.ts:90-190 是一个 defineStack({ manifest: { id, namespace: 'crm', type: 'app' }, objects: Object.values(objects), apps, flows, … })——定义体直接 import，不是 glob。CLI 侧：loadConfig（packages/cli/src/utils/config.ts）→ 校验 / lint / lower → buildRuntimeBundle（utils/build-runtime.ts）。
• 两阶段错配（ArtifactPackageEntrySchema's body half cannot describe the payload the load path actually registers #14242）：ArtifactPackageEntrySchema.manifest = ManifestSchema，其 objects 是 z.array(z.string())（作者态 glob）；而装载侧 resolveArtifactPackageOrder（packages/objectql/src/artifact-packages.ts）把每个 packages[i].manifest 交给 ObjectQL.registerApp，后者把 m.objects 当定义体迭代。ADR-0130 D5+D7: register an artifact's N packages in topological order, reusing resolvePluginOrder #14240 因此只把 schema 当 wrapper 门用，并在模块头记录了这个错配。
• validateSingleApp（stack.zod.ts:948，在 :1854 由 defineStack 调用）对 type:'app' 强制单应用（ADR-0019）。composeStacks 在 stack.zod.ts:2451，'preserve' 语义见 :1907-1946。

决定（维护者 2026-09-02 在 PM 会话拍板）

#14242 取 B：给装配/注册态的包体一个独立声明；作者态 ManifestSchema.objects 不加宽（否决 C）；A 的"只声明 wrapper 门"作为过渡状态随本卡终止。

要做

1. spec：声明装配后的包体 schema（命名由 dev 提，如 AssembledPackageBodySchema）：manifest 字段 + 与 ObjectStackDefinitionSchema 相同的定义数组键（objects / apps / flows / …，键集从同一处派生，不手抄）。发布物层的 packages[] 引用它；作者态入口仍是 ArtifactPackageEntrySchema（manifest-only）。装载门从 wrapper-only 改为对装配态声明完整 parse，artifact-packages.ts 模块头里对错配的记录同步改写。
2. 作者态形状，不发明第二种写法：一个项目 = N 个各自合法的 defineStack（每个仍受 ADR-0019 单应用约束）+ 一个项目级 config 调 composeStacks([...], { manifest: 'preserve' })。⛔ 不放宽 validateSingleApp：组合后的项目物按 packages[] 迭代，单包路径一字不动。
3. CLI os build / compile：loadConfig 得到的定义带 packages[] 时，对每个包分别走今天单包的校验 / lint / lower 路径（同一套函数，不复制一份），产出一个发布物 JSON，packages[i] 为装配后包体；os dev 同样能起它。单包输出 bit-identical（D7 pin 已有，必须保持绿）。
4. 夹具：examples/app-multi-package/（名字 dev 定）：两个包共享一个命名空间，一个 type:'app'、一个 type:'module'（无 scope 键），各一个对象，模块对象 lookup 到应用对象；pnpm build 出 packages[]；dogfood 测试起服务，断言 GET /api/v1/packages 两行（feat(packages): GET /packages and GET /packages/:id rows carry the server's own writable verdict (isWritablePackage) #14430 合并后追加 writable: false 两行断言）。
5. 文档：作者态页（content/docs/plugins/packages.mdx 或 dev 判定的正确页）加一节"项目 = 多包发布物"，⛔ 不碰 content/docs/releases/。
6. 消融：删 CLI 的 packages[] 分支 → 夹具构建断言红；删装配态 schema 门 → 错形包体不再被拒（各自预测红集、复原按字节、经 dist 的腿要重建并 preflight）。

边界

⛔ 不动 marketplace / 安装面（ADR-0019 D2/D3，发布物停在控制面）。⛔ 不做跨发布物共有权（ADR-0130 D8）。⛔ ManifestSchema.objects 不加宽。⛔ 不改 ADR；若 ADR-0130 需要补记 D4 的两阶段声明，另开 docs-only 卡给维护者。

Clause-②

预期 YES：编译的接受 / 拒绝面变了（新的装配态 schema 门、CLI 新分支、装载门从 wrapper 变完整 parse）→ 挂 needs:contract-review，PR 留 draft，PM 复审。

验收

夹具 build + boot 全绿并留 GET /api/v1/packages 原文；D7 单包 bit-identity pin 绿；packages/spec、packages/cli、packages/objectql 全量绿；dispatch-gates 联合零发现；PR 同时 Fixes #14242。changeset：@objectstack/spec minor、@objectstack/cli minor、@objectstack/objectql patch。

[hotlong]

认领

• 会话：session_01UHvF5hyiZjnCyExFnfQB8m（epic One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 的 PM 席）
• 分支：claude/issue-14439-multi-package-build
• 派发：os-dev，单卡，工作树 objectstack-14439
• 与在飞 PR feat(packages): GET /packages and GET /packages/:id rows carry the server's own writable verdict (isWritablePackage) #14430（packages/runtime、packages/metadata-protocol）无文件交集；ADR-0130 D5+D7: register an artifact's N packages in topological order, reusing resolvePluginOrder #14240 留在 packages/objectql/src/artifact-packages.ts 模块头的错配记录由本卡改写。
• 发版等本卡：不走捷径，但不要把范围做大——边界见卡面。

---

Generated by Claude Code

[hotlong]

补充事实：装配后的包体要过三道 parse，不是一道

objectui#7177 的 dev 在 bd0ee2fb 上做了一次诚实的 os dev 多包启动尝试（PR objectui#7331 正文），我按锚点复核过：

道	位置	今日行为
作者态	defineStack 对 ArtifactPackageEntrySchema.manifest 用作者态 ManifestSchema 完整 parse	packages.0.manifest.objects.0: Expected string but received object（原文）
编译	packages/cli/src/commands/compile.ts:271 ObjectStackDefinitionSchema.safeParse(lowering.lowered)；同一 parse 也在 scaffold-validate.ts:76、validate.ts:187、lint/score.ts:69	装配后的 packages[i] 要能过
装载	packages/metadata/src/plugin.ts:891 _parseAndRegisterArtifact → :912 ObjectStackDefinitionSchema.parse(this._convertArtifactForward(...))，在 D4 的 manifest.register() 之前对整个发布物硬 parse	dev 实测：含 objects + permissions 的包体 4 处失败；去掉 permissions 2 处；两者都去掉才过；flows / apps 等在 ManifestSchema 上未声明，被 parse 副本剥掉、只在原始体里存活 —— 所以 Data 与 Access 两个分区正是 D4 缝今天带不过去的

对 B 向的含义：packages[] 在 ObjectStackDefinitionSchema 里必须引用装配态声明（第 2、3 道 parse 的就是它），作者态入口留给 defineStack 装配前所见；编译一步是两者的转换点。若一个 packages 键做不到两态兼顾，在 PR 里明说并提出拆法，⛔ 不以加宽 ManifestSchema.objects 了事。每道缝一条 pin：两包装配物在 :271 与 plugin.ts:912 都能过；错形体在正确的阶段被拒且信息点名阶段。已同步给在飞的 dev。

---

Generated by Claude Code

[hotlong]

落地后的验收追加项（PM 负责，不加进 dev 的范围）

objectui#7177（PR objectui#7331）的多包 Studio 验证——切换器同时列出 app 与 module 包、module 标只读、/studio/<module>/{data,automations,access} 三个分区按包过滤——因今天编不出 packages[] 发布物而未跑（dev 的一次诚实尝试与拒绝原文见该 PR 正文）。本卡的 examples/app-multi-package 夹具落地后，PM 用它复跑这组验证；若三个分区有任一不按包过滤，按平台缺口另立卡，不在 objectui 绕。

同时把 objectui dev 已探明的一条 API 线索留在这里备用：Studio 各分区走 client.list(type, { packageId })，线上参数名是 package（GET /api/v1/meta/<type>?package=<id>）。

---

Generated by Claude Code