起草 ADR:发布物作为共同所有权边界 —— 一个发布物、物内 N 个包(#14122)

[os-sam]

裁决(2026-09-01,维护者,逐字)

立 ADR 起草卡派发

语境:总监席对 #14122(hotlong,一物 N 包提案)的评估结论为「方案合理,建议接受;应当先写 ADR 再派实现」,维护者以上句批准进入 ADR 起草通道。终局接受/修订在 ADR draft PR 的人工合并上落定,本卡只产出 ADR 草案。

交付物

docs/adr/ 新增一篇 ADR(编号取现有最大号 +1,起草时以 ls docs/adr 实测为准),主题:发布物(release artifact)作为共同所有权边界 —— 编译按包、产物一个 JSON、物内保留 N 份 manifest、装载按依赖拓扑序注册 N 个包。Status: Proposed。

必须涵盖(取向已裁,ADR 负责论证与留痕)

1. Context:引 One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 的实测证据(fork 税、Studio 平铺、token 预算无模块边界、CPQ 无可售单元),以及 §2 三条替代路的否决理由(module 标签 = 假模块无边界原语;独立命名空间 = rename-on-install,ADR-0048 明拒;composeStacks = 压平丢身份)。
2. Decision 核心原则:同一发布物内的包由同一发布者原子交付,物本身即共同所有权声明——安装闸判据从「同一包 id」修正为「同一物内共同所有者」;⛔ 不新增 manifest owner/publisher 字段(推迟至模块独立成物售卖时,与 ADR-0048 2026-08-08 addendum D2 对齐,记入 Non-goals)。
3. 对 ADR-0019 的边界记录:消费者模型一根不动(装一个/开一个/卸一个,D1-D3 原样);发布物停在控制面,⛔ 永不成为消费者可浏览/安装/卸载的 suite(D3 苹果论证原样适用);D4「a set of namespaces」原文即容纳本案。按仓内惯例以交叉引用/addendum 记录,⛔ 不改写 0019 原文。
4. 对 ADR-0048 的闸变更记录:命名空间独占今天顺带代理着「无两包同名对象」;放宽(§5.4)必须与安装时逐对象名唯一性检查(§5.6)同批,且机器不可拆——同一 PR 落地 + 一条门测试断言「闸已放宽 ⇒ 唯一性检查存在且拒绝同名对象」。写入 Consequences 作机器判据。
5. 产物 schema 决策:manifest 单数 → packages: [...],新增可选键、两种都读(有 packages 遍历,无则把 manifest 当单元素列表);前向兼容走既有 manifest.engines.protocol;分段加载的键位在本 ADR 定稿时预留(不必实现,但格式是最难回头改的决策,One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 ④)。
6. 拓扑序为验收条件而非实现细节:物内包注册必须按依赖拓扑序,复用 resolvePluginOrder(⛔ 不写第二排序机制);顺序错误静默失效(扩展不生效不报错),必须有测试钉住。
7. 一物一版(One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 ③ 已认):版本矩阵消失、扩展不悬空;代价(不能单独热修模块)如实写入;要单独售卖的模块独立成物。
8. 兼容性与验收:存量单 manifest 产物经新装载路径注册结果逐位相同(包记录、对象 FQN、_packageId、命名空间所有者集合)——写成测试的机器判据(One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 §6.4),不靠 review 判断。
9. Consequences 枚举后续实现面(One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 §5 表,含 objectui 侧 Studio 选择器另开),实现卡待 ADR 合并后按 ADR 派发,⛔ 本卡不写实现代码。

起草纪律

• 先通读 One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122 全文(含修订 1)、ADR-0019、ADR-0048(含 addendum)、必要时 ADR-0003/0005;引用逐字,锚点给文件行号。
• 总监席已抽查核实的锚点:0019 D4 原文、0048 三处 rename-on-install non-goal、registry.ts:1456 多所有者 Map、registry.ts:3582-3595 命名空间闸——可直接引用。
• docs/adr/** 是受管面:PR 恒 draft,终局为维护者直合或钉头批准入队;⛔ 不入队不转 ready。
• 遵守 ADR 目录既有格式惯例(读近期两三篇为样);docs-only diff 按仓内惯例决定是否需要 changeset(实测 --test 与 lint 门为准)。

关联

• 提案与全部实测证据:One artifact, N packages: let a release bundle carry co-owning packages so a product can be split into modules without renaming objects #14122(hotlong)
• 总监席评估(四维,长期 ≥50%):见 PM 会话 2026-09-01 记录,结论「合理,建议接受」

[os-sam]

Claim

Session: session_015adLit3ZYASJiXwxKG78Wi (dispatching PM / director seat)
Branch: claude/issue-14144-adr-one-artifact-n-packages

Starting the ADR drafting work now (prose-only, docs/adr/**). Re-read existing comments before starting: none present, no competing claim.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

os-dev-report

{
 "issue": 14144,
 "status": "done",
 "branch": "claude/issue-14144-adr-one-artifact-n-packages",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/14151",
 "premise_still_valid": true,
 "adr_number": "ADR-0130 (docs/adr/0130-release-artifact-as-co-ownership-boundary.md)",
 "summary": "Authored ADR-0130 'The release artifact is the co-ownership boundary — one artifact, N packages', Status Proposed, as a prose-only diff: one new file, nothing outside docs/adr/**. It covers all nine required items from #14144 as eight decision letters — D1 artifact-as-co-ownership with the install gate's criterion corrected from 'same package id' to 'co-owners within one artifact'; D2 the ADR-0019 consumer model unmoved and the artifact stopped at the control plane (0019 D3's suite ban restated as the line not to cross); D3 the 5.4 gate relaxation and 5.6 install-time per-object-name uniqueness check recorded as MECHANICALLY inseparable (same PR plus a gate test asserting the pair, asserting error code and status per the ADR-0112 envelope rather than a bare throw); D4 artifact schema manifest to optional packages array, read-both, forward compatibility on manifest.engines.protocol, segmented-loading key position reserved at schema time; D5 topological ordering as a machine acceptance criterion by reuse of resolvePluginOrder with the silent-failure warning and a BEHAVIOURAL pin rather than a permutation assertion; D6 one-artifact-one-version with the no-per-module-hot-fix cost stated plainly; D7 bit-identical legacy registration as an automated test; D8 no owner field, deferred with a named trigger aligned to the ADR-0048 2026-08-08 addendum D2. Consequences enumerate the #14122 section 5 implementation surface, with the Studio picker marked objectui-side. No original text of ADR-0019 or ADR-0048 was edited — the boundary is recorded by cross-reference per the additive-addendum convention 0048 itself uses. ADR number chosen as max+1 measured at the branch point (0129 is the highest on origin/main); no ADR mirror exists under content/docs, so the file is the whole deliverable. Changeset: skip-changeset LABEL applied (not a changeset file) — the diff publishes nothing from any package; applied additively via REST POST and read back after the size-labeler window, where it survived alongside size/l. PR is DRAFT and stays draft: docs/adr/** is a governed surface and the maintainer's hand-merge is the acceptance act.",
 "tests": "All on the final commit 341b9e9 (git rev-parse --short HEAD from the run that produced these results; tree clean, nothing uncommitted). Exit codes captured BEFORE any pipe (redirect to a file, then read $?); every verdict below quotes the gate's own printed line. (1) DERIVED FAMILY — node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack derived 5 families from 1 changed path; all 5 green: check:adr-anchors EXIT=0 'check-adr-anchors: OK (52 anchored file(s), every governing ADR still referenced; 128 decision number(s), each naming one decision or an allowlisted pair; 30918 citation(s) across 3981 file(s) resolve; 933 decision-letter citation(s) ... name a decision the record makes)'; check:doc-authoring EXIT=0 '395 files clean' + '48 published skill files clean' + '14317 customer-facing string(s) across 694 spec sources clean'; check:pm-governed-merges EXIT=0 '243 assertions'; node scripts/check-adr-links.mjs EXIT=0 '598 relative link destination(s) under docs/adr/ resolve'; pnpm --filter @objectstack/lint run check:doc-formula-expressions EXIT=0. (2) NOT-MEASURED CAUGHT AND RESOLVED — doc-formula-expressions first returned EXIT=3, which the gate itself prints as 'PREREQUISITE NOT MET ... Nothing was measured ... It is NOT a finding'. Two prerequisites in sequence: @objectstack/formula unbuilt, then @objectstack/lint unbuilt. Both built under the shared verify lock (scripts/pm/os-verify-lock.sh, VERDICT command-exit 0, held 183s and 16s) and the gate re-run to a real EXIT=0. The exit-3 reading is NOT reported as a pass or a failure. (3) FULL 'Lint & Repo Gates' JOB, per the binding #14061 lesson — the job's own step list harvested programmatically from .github/workflows/lint.yml rather than derived: 138 steps total, 4 are uses: actions (checkout/setup-node/setup-pnpm/cache, not locally runnable), 134 are run:, and ZERO carry an if: — confirming CI runs every one on every PR. 132 of the 134 executed locally against 341b9e9, all EXIT=0. The 2 not run are pure CI setup with no local meaning: 'Get pnpm store directory' (writes $GITHUB_ENV) and 'Install dependencies' (pnpm install --frozen-lockfile, already satisfied in the worktree). The 132 include ESLint (pnpm lint, repo-wide, --no-inline-config) which ran under the verify lock to VERDICT command-exit 0 in 75s — NO narrowing was taken and none is claimed. (4) GOVERNED-SURFACE VERDICT — node scripts/pm/check-governed-merges.mjs --test docs/adr/0130-...md printed 'governed-surface predicate: 1 of 1 path(s) hit the register' and 'GOVERNED — a human merge is the review record for this PR (#9495 regime)', exit 3 being that gate's declared GOVERNED code, not an error. Verdict stated in the PR body as required. (5) Control-byte self-scan over the new file (grep -naP over the C0/DEL classes) matched nothing; check:nul-bytes is also inside the 132. No ablation was performed — this is a prose-only diff with no code path to mutate, so the ablation clause does not apply and no rebuild/on-disk-mutation evidence is claimed. PR body read back in full after creation (6812 bytes): first line 'Fixes #14144' intact, session-URL footer intact, and ten load-bearing spot-check strings all present — no sanitizer damage. draft:true, base:main confirmed by live API read.",
 "mcp_calls": "6 — issue_read get 14144, issue_read get_comments 14144, issue_read get 14122, issue_read get_comments 14122, add_issue_comment (claim), create_pull_request. This report comment makes 7. Bulk verification, label writes and the PR/label read-backs went through git and repo-scoped REST (probed first: HTTP 200), not MCP.",
 "open_questions": [
 {
 "question": "D8 — should the manifest owner/publisher field be deferred (as drafted) or land in the same batch as the ADR-0048 2026-08-08 addendum D2? #14122 待决策 ⑤ asked this explicitly; the director-seat evaluation recorded '⑤owner 字段推迟' and the draft follows that, so merging the ADR accepts the deferral.",
 "options": [
 "A — defer, as drafted (D8): within one artifact the field restates what atomic delivery already proves, and a second source of truth for ownership can drift from the first; the named trigger is the day a module ships as its own artifact",
 "B — add the field now, aligned to addendum D2's publisherOrgId key; adds one row to #14122 §5 and pulls cross-artifact co-ownership forward"
 ],
 "recommendation": "A — it is what the director-seat evaluation already recorded and what the draft implements; the deferral is written with an explicit trigger rather than left as an absence, so B stays cheaply reachable. Flagged only because #14122 asked the maintainer to say so directly."
 },
 {
 "question": "Recording convention for the ADR-0019 boundary (item 3): cross-reference from ADR-0130 only, or additionally a one-line Related entry added to 0019 pointing here?",
 "options": [
 "A — cross-reference from 0130 only, as drafted; 0019 is untouched",
 "B — additionally add one Related line to 0019 (additive, superseding nothing), so the amendment is visible from 0019 itself"
 ],
 "recommendation": "A for this PR, because #14144 says ⛔ never rewrite 0019, and the safest reading of that is to touch nothing in it. The draft names B explicitly as an additive follow-up the maintainer can call for, so choosing B costs one line and no rework."
 },
 {
 "question": "D6's cost acceptance — 'no per-module hot-fix' is a real operational cost landing on whoever supports the product. #14122 待决策 ③ recorded it as already conceded; the ADR states it plainly rather than softening it.",
 "options": [
 "A — accept as drafted; a module needing its own cadence becomes its own artifact",
 "B — revisit before merge if any shipped module already needs independent hot-fix cadence"
 ],
 "recommendation": "A — the escape hatch is structural (own artifact) rather than a special case, and it is the same trigger that ends D8's deferral, so the two stay consistent."
 }
 ],
 "out_of_scope_findings": [],
 "premise_verification_notes": [
 "#14122 cites objectql/src/engine.ts:4745 for registerApp — OFF BY ONE. registerApp(manifest: any) is declared at :4746; :4745 is the closing */ of its doc block. The claim it supports (registration is per-manifest, stamping that manifest's id/namespace) holds exactly as described. Recorded in the ADR's §7, not silently corrected.",
 "#14122 §1.3b cites scripts/check-source-token-ratchet.mjs — that file DOES NOT EXIST in objectstack-ai/objectstack; grep across the worktree finds no occurrence of the name. It is a downstream application repo's script, so the 178,417/180,000 measurement is downstream evidence about the apps rather than a gate in this repo. This does not weaken the argument: the platform-side half was verified independently here — the object document carries no grouping/module/category key, and the only 'group' spelling in packages/spec/src/data/object.zod.ts:1779 is a rejection-guidance entry redirecting the author to the view's userActions. Recorded in §7.",
 "Everything else in #14122 that is checkable in this repo was re-verified and found exactly as described: registry.ts:1456 namespaceRegistry = Map<string, Set<string>>; the installPackage namespace gate at :3575 with the conflictOwner criterion at :3583 and the throw at :3595; getNamespaceOwners returning an array at :1540; unregisterObjectsByPackage at :2679; plugin.ts:405 ql.registerApp(manifest); stack.zod.ts:240 (artifact manifest is singular and optional on ObjectStackDefinitionSchema, which compile.ts:271 parses and :596 writes, with os build an alias of os compile per build.ts:6); stack.zod.ts:854 validateSingleApp returning [] for every type other than 'app'; stack.zod.ts:1759 composeStacks manifest option quoted verbatim; RESERVED_NAMESPACES = Set(['base','system']) at registry.ts:45 with isShareableNamespace adding 'sys' at :1116; resolvePluginOrder at packages/core/src/plugin-order.ts:66; and ADR-0048's rename-on-install non-goal in all three of its recorded places (:57-59, :171, :261-267). The dispatch-supplied anchors (0019 D4 text, 0048's three non-goal sites, registry.ts:1456, registry.ts:3582-3595) all held.",
 "No competing claim existed on #14144 — comments were empty before the claim comment was posted. Assignee was already set by the PM and was not touched."
 ]
}

---

Generated by Claude Code