Repository navigation
Commit afe6ab9
docs(adr): ADR-0141 — an app may depend on another installed app: declared in manifest.dependencies, checked once before install, co-owning the namespace it shares (#25717)
<!-- claude-projects-attribution: {"github_login":"marchtian"} -->
_Requested by **田騏** · [project
thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSiSy7TyERBjGhY2v7KGu8Gai)_
Fixes #25403
Clause-②: no
Metadata-protocol: none
Docs-only, Tier H (`docs/adr/**`): the PR stays draft and the maintainer
merges it. Records the two maintainer rulings on #25403 — B′
(`6369704387`) and the namespace letter A (`6377678758`) — as a new ADR,
and makes the three neighbouring records say the same thing.
## 维护者速读(草稿)
**改了什么**
新增 ADR-0141,把「应用 B 可以声明依赖应用 A」写成契约:声明沿用
`manifest.dependencies`,引用沿用保存门的依赖闭包;唯一新增的关口是**安装前检查**(依赖已装、版本在范围内,同一发布物内送达的依赖只看在不在,否则拒绝并说明缺什么,填上预留的
`dependency_missing`;检查支持的版本范围文法由运行时卡写明,作者侧 `os lint` / `os validate`
先于安装报出读不懂的范围);声明了依赖且命名空间相同的包,在安装门上与被依赖方**共有命名空间**(单向,门禁从任一端读取;同一被依赖方下的两个模块互为同门,不必互相声明),前提是主应用发布物里共用该命名空间的其余包也直接声明主应用(注册表安装后不记录包来自哪个发布物);开机重注册的两条路径各自按
`manifest.dependencies`
排序后再注册,对象名唯一检查跨发布物同样生效。卸载保护、升级拦截、拓扑/连带安装、被引用方发布标记、市场版本协商、安装后通过 PATCH 改动
`dependencies` 的判定,逐项写为推迟项;D8 的快照记录到数组转换另立一张卡;权限不变。另外三处配套:ADR-0028 D4
改为「未声明依赖不得跨应用引用」;ADR-0019 只加一行交叉引用(原文不改);ADR-0130 加附录,D8
的推迟改为「到市场发布时结束」,并标注它关于 #14488 的那一行已过时。
**为什么改**
你在 #25403 批了 B′ 和命名空间 A。HotCRM 想把 revenue
等模块拆成可以单独安装的包(「而每个包可以独立安装」),今天做不到:安装时没有任何地方检查依赖是否已装,单独发布的模块还会因为共用 `crm`
命名空间被安装门拒绝。这份 ADR 定下契约,运行时卡在它合并后再切。
**风险与代价(含回滚)**
只改文档,不动代码和 schema。业务上的代价写进了
ADR:卸载或升级被依赖的应用暂时不拦(推迟项),管理员可能把依赖方晾在那里;单独发布的模块和主应用各有版本号,ADR-0130
在同一发布物内消除的版本矩阵会在跨发布物时回来,只靠声明的版本范围约束。合并后的运行时卡按 S 估(裁决原估检查本身为
XS–S),另有作者侧规则和快照转换两张小卡。回滚:撤销本 PR 的合并即可,没有任何运行时状态。
**席位意见**
**你要做的**
读 ADR 里「Open questions for the maintainer's merge
decision」十二条(第一至四条与第十一、十二条定机制:同一发布物内送达的依赖算已装且只看在不在;只在三个安装动作时检查,开机重注册和安装后的
PATCH 改动都不检查;命名空间共有关系由依赖方单向声明,门禁不论哪一方后注册都按这一条声明判定,否则装了模块之后 HotCRM
自己就再也升不了级;只认直接声明,外加「同一被依赖方下的模块互为同门」这一条,否则第二个模块就不能独立安装;安装后 PATCH 改
`dependencies`
暂不判定,这道门只到得了手工编写的包,且整体改写可以删掉作为共有凭据的那一条;开机重注册的两条路径各自用同一个排序器按
`manifest.dependencies` 排序后再注册,而不是让同门规则在父包未注册时放行。五至八条定拒绝的形状:422(同一道门上也有
409 的先例,取 422
是与注册表门禁一族一致);版本或范围解析不了即拒绝,与协议握手的「警告并放行」相反,并要求运行时卡写明支持的文法,树里三个读取器没有一个兼有完整文法与精确到补丁号的粒度,扩展握手那一族;每条声明都是必需、`optional`
投影为 false;只判本包自己的声明。第九条:D8 的记录到数组转换另立一张卡,先读控制面怎么解析快照。第十条:对 #14488
裁决的读法,「发布物整体安装」未变,「不需要单独安装一个模块」所否定的需求如今由另一个发布物满足,即该裁决自己点名的拆出路径)。另有一条
HotCRM 侧前提尚未核实:sales 发布物里其余 `crm` 包须直接声明 sales,否则模块安装和 HotCRM
升级都会在命名空间门上被拒。同意就合并,合并即接受;有异议就在 PR 里点出哪一条。
## What changed
| File | Change |
|:---|:---|
|
`docs/adr/0141-inter-app-dependency-declared-checked-before-install.md`
| New record, **Proposed**. D1 declaration and reference (no new
mechanism) · D2 the pre-install check (what it judges — an installed
record for presence and range, a co-delivered package for presence only;
422 + a ledger-registered code + one `dependency_missing` issue per
unmet entry; the three install acts it runs at, the three
re-registration paths and the manifest `PATCH` it does not; fail-closed
on an unparseable range, the opposite of the handshake beside it, paired
with a stated range grammar — none of the tree's three readers has both
the documented grammar and exact-version granularity; the handshake
family in `metadata-core` is extended as a sibling function, the
handshake's verdicts unchanged — and an author-side `os lint` / `os
validate` rule) · D3 the six deferred items, each with its interim state
and trigger (the `PATCH` item noting the door reaches only authored
packages and can delete D5's proof) · D4 permissions unchanged,
record-level semantics an open section of three questions (incl. the
ADR-0086 D4 own-namespace discriminator that D5 dissolves across
artifacts) · D5 dependency-declared namespace co-ownership, one-way,
read from either end (the gate refuses any sitting owner outside the
co-owner set, so HotCRM could not otherwise be upgraded once a module is
installed — and the free upgrade guard that brings), with a sibling arm
(two modules under one declared parent that holds the namespace), the
precondition that the app's own companion packages declare it, and the
requirement that each hydrate path sorts its batch through the one
sorter (the seals and the never-recovered refusal otherwise; ledger
entries as nodes; a cycle degrades to source order, never throwing out
of the hydrate), D3 uniqueness across co-owners and siblings, ADR-0130
D8's deferral now ending at marketplace publishing · D6 what
ADR-0028/0019/0130 now say · D7 the first consumer (a HotCRM module
shipping alone as `type: 'app'`, revenue first) with three HotCRM-side
preconditions, not re-verified · D8 the three dependency shapes; the
record-to-array snapshot conversion split off as its own card · a
merge-decision list of twelve drafter choices (1–4, 11 and 12 the
mechanism, 5–8 the refusal's shape, 9 the D8 conversion as its own card,
10 the reading of ruling `5645322259`) |
| `docs/adr/0028-metadata-naming-and-namespace-isolation.md` | D4
rewritten to "no cross-app reference without a declared dependency",
with a note quoting the original sentence; the two dependent sentences
(D6, leak-point 3) and TL;DR item 4 follow; status line gains an Amended
entry. The rest of the record stays Deferred |
| `docs/adr/0019-app-as-consumer-unit.md` | One additive `Related`
header line; text unchanged (ADR-0130 D2's recording convention) |
| `docs/adr/0130-release-artifact-as-co-ownership-boundary.md` | One
status-header entry and an addendum at the end: D8's deferral end point,
and the 2026-09-02 addendum's #14488 line marked stale (that card's
state is `not_planned`, ruling `5645322259`). No original text edited.
The addendum names the sibling arm beside the one-way relation, and
quotes, byte-exact, ruling `5645322259`'s premise sentence, reading it
in two halves: an artifact installs whole (unchanged, D2 stands); the
need its second half denied is now met by another artifact, the
carve-out path the ruling itself named; its disposition stands |
## Measurements (at `origin/main` `47af3dde42`)
- **Dispatch assumption "nothing at install reads
`manifest.dependencies`"** — holds for checking, fails for ordering by
one reader: `resolveArtifactPackageEntries`
(`packages/core/src/artifact-packages.ts`) feeds every declared id to
`resolvePluginOrder` as an optional edge and skips an id outside the
artifact silently. No install door checks presence or version;
`dependency_missing` occurs only in `app-install.zod.ts`, its test and
`content/docs/references/system/app-install.mdx` — the only three
tracked occurrences (zero producers). Recorded in the ADR's Context and
Verification notes; no decision moves.
- **Dispatch assumption "the namespace refusal is
`NamespaceConflictError` in `packages/objectql/src/registry.ts`"** —
holds. Gate and throw are `SchemaRegistry.installPackage` /
`NamespaceConflictError`; the co-owner set is
`ArtifactInstallScope.packageIds` (artifact scope only);
`refuseCoOwnedObjectNameCollision` reads the same set and skips
non-co-owners by design, which is why D5's one added source makes both
halves of the ADR-0130 D3 pair follow. The line numbers the HotCRM input
and the ruling cite have moved; the ADR cites symbols.
- **Three dependency shapes, not two**: the manifest record, the
marketplace `PackageDependencySchema` array, and a third —
`AppManifestSchema.dependencies`, bare ids with no range, in the same
file as `dependency_missing`, no reader outside `packages/spec`. `os
package publish` snapshots the record shape into `manifest_json`, whose
declared schema is the array; the control-plane side lives in
`objectstack-ai/cloud` and is not measured.
- **ADR number**: `0136` and `0140` belong to proposals that never
landed (PR #18480 closed 2026-09-18, superseded by the North Star; PR
#25618 withdrawn 2026-10-24 by the maintainer's ruling in session); no
landed record or open PR carries either number. This record is `0141`.
- **In-repo declaring population**: one manifest,
`examples/app-multi-package` (orders → core, same artifact); each
package declares its own `version: '1.0.0'`, and `composeStacks(…, {
manifest: 'preserve' })` keeps each manifest as authored — why D2 counts
a co-delivered dependency as present and judges it for presence only.
- **Range readers, three**: `rangeAdmitsMajor` /
`alternativeAdmitsMajor`
(`packages/metadata-core/src/protocol-handshake.ts`) read
`*`/`x`/`latest`, `^`, `~`, `N.x`, `||`, space- or comma-joined
intersections, hyphen ranges and bare versions, but at major granularity
(`^6.2.0` admits 6.1.0); `parseRangeFloor` (same school, by its
docstring) computes a floor only; `SemanticVersionManager`
(`packages/core/src/dependency-resolver.ts`) compares full versions over
a narrow grammar (`6.x`, intersections and `||` answer false or throw;
`^6` throws in `parse`) and has no caller in `packages/` outside its own
file and test. No package under `packages/` imports a semver library
(root `semver` is a devDependency).
- **`PATCH /api/v1/packages/:id`**
(`packages/runtime/src/domains/packages.ts`) first runs
`requireWritablePackage(…, 'edit')` — `422 WRITABLE_PACKAGE_REQUIRED`
for a package provided by code or an installed app (ADR-0070 D2) — then
rewrites `dependencies` whole by reference to
`ManifestSchema.shape.dependencies`, with no in-use check; it can delete
an entry. The post-install edit D3 defers (merge question 11).
- **Hydrate order**: the `sys_packages` hydrate
(`packages/services/service-package/src/index.ts`) iterates
`packageService.list()` and, on an `installPackage` throw, logs the
package "was NOT hydrated into the registry" and leaves it absent for
the process; the install-local `kernel:ready` rehydrate registers ledger
entries in `readdirSync` order (`local-manifest-source.ts#list`).
`InstalledPackageSchema` records no artifact; the manifest service's
scope is not persisted. Hence D5's companion precondition and the
per-path sort (merge question 12). `resolvePluginOrder` throws on a
cycle through either edge kind and `resolveArtifactPackageEntries` keeps
that throw for one artifact; D5 states the hydrate sort does not inherit
it (cyclic members fall back to source order with a logged refusal).
## Gates
Derived with `node scripts/pm/dispatch-gates.mjs --commands` (change set
vs merge base `47af3dde4`, 4 files, +851 / −16), all 20 run at head
`02456273` (re-derived on that head), every one `exit 0`:
`check-adr-links` (+ `--self-test`), `check-adr-symbol-anchors` (+
`--self-test`; 2473 anchors across 143 records resolve),
`check-ci-filter-parity`, `check-closing-keyword-parity` (+
`--self-test`), `check-comment-mask-corpus`, `@objectstack/lint
check:doc-formula-expressions`, `check:adr-anchors`,
`check:closed-ceremony-text`, `check:cross-package-test-inputs`,
`check:doc-authoring`, `check:driver-memory-census`,
`check:gitlink-declared`, `check:nul-bytes`, `check:pm-governed-merges`,
`check:pm-prior-rulings`, `check:refd-timer-probe`,
`check:watch-hint-literal`.
`dispatch-gates --ran`: 20 derived, 20 run, 0 NOT-MEASURED, 0 UNRUN (a
derived zero — every line carried its exit code).
The record was re-drafted at `247fe2fa` at `CONTRACT_REVIEW_TIER` with
effort xhigh, on the owner's order that ADR text runs at that tier (card
#25729). Contract review PASS at `247fe2fa` (comment `6392433266`); its
five nits landed in `fa733808`. The independent review's eight accepted
items (「全部照改」) landed in `2bf30f03`. The independent full review of
`2bf30f03` (PASS WITH FIXES, F1–F11) landed in `5c4071ef`. The delta
review of `5c4071ef` (PASS WITH FIXES, N1–N4) landed in `02456273`. The
final delta check of `02456273` is PASS (record on this PR).
No changeset: `docs/adr/**` publishes nothing (`skip-changeset`).
## Acceptance notes
- hotcrm `docs/architecture/module-split-plan.md`, hotcrm#2270 and
hotcrm#2271 are cited as the rulings cite them; that repository is not
readable from this session.
- Ruling `6369704387` says "`revenue` first per ADR-0130 §1.3(c)";
§1.3(c) names CPQ as the unsellable module. The ADR records
revenue-first as HotCRM's own ordering; nothing moves.
- D5's "read from either end" and sibling arm are the drafter's reading
of the ruling's "one-way" (who declares and who gains stay one-way);
they hold for HotCRM only if the app's companion packages (service,
marketing) directly declare sales — the registry keeps no artifact
record after install, so a companion is otherwise a foreign sitting
owner that refuses the module's install and the app's next upgrade. Not
verified in HotCRM: Open item 7, the HotCRM lane's reading. Boot order
is decided, not read: each hydrate path sorts its batch through
`resolvePluginOrder` (merge question 12) — ledger entries as nodes in
the install-local path, a cycle degrading to source order rather than
throwing out of the hydrate —; cross-path order and the `kernel:ready`
seal/hydrate hook order are Open item 2.
- D4's open section carries the ADR-0086 D4 discriminator question;
nothing in-repo was measured to refuse a package's permission set naming
another package's object — recorded as open, not decided.
- The ADR's merge-decision list now names twelve drafter choices (the
contract review's D(5)–(10) are items 5–10; 11 and 12 are new): 422 over
the 409 precedents; fail-closed parse with a stated grammar, extending
the handshake reader family; required entries / `optional` → false; own
entries only; the D8 conversion as its own card; the two-halves reading
of ruling `5645322259`; the post-install `PATCH` deferred (authored
packages only); each hydrate path sorting by `manifest.dependencies`.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01HwUcNzGjPhV6xtYkJ469qK)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent bb85f5f commit afe6ab9
4 files changed
Lines changed: 851 additions & 16 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| 8 | + | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| |||
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
36 | | - | |
37 | | - | |
38 | | - | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
39 | 42 | | |
40 | 43 | | |
41 | 44 | | |
| |||
152 | 155 | | |
153 | 156 | | |
154 | 157 | | |
155 | | - | |
156 | | - | |
157 | | - | |
158 | | - | |
159 | | - | |
160 | | - | |
161 | | - | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
162 | 180 | | |
163 | 181 | | |
164 | 182 | | |
| |||
232 | 250 | | |
233 | 251 | | |
234 | 252 | | |
235 | | - | |
236 | | - | |
| 253 | + | |
| 254 | + | |
| 255 | + | |
237 | 256 | | |
238 | 257 | | |
239 | 258 | | |
| |||
257 | 276 | | |
258 | 277 | | |
259 | 278 | | |
260 | | - | |
261 | | - | |
262 | | - | |
| 279 | + | |
| 280 | + | |
| 281 | + | |
| 282 | + | |
| 283 | + | |
263 | 284 | | |
264 | 285 | | |
265 | 286 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
9 | 9 | | |
10 | 10 | | |
11 | 11 | | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
12 | 19 | | |
13 | 20 | | |
14 | 21 | | |
| |||
743 | 750 | | |
744 | 751 | | |
745 | 752 | | |
| 753 | + | |
| 754 | + | |
| 755 | + | |
| 756 | + | |
| 757 | + | |
| 758 | + | |
| 759 | + | |
| 760 | + | |
| 761 | + | |
| 762 | + | |
| 763 | + | |
| 764 | + | |
| 765 | + | |
| 766 | + | |
| 767 | + | |
| 768 | + | |
| 769 | + | |
| 770 | + | |
| 771 | + | |
| 772 | + | |
| 773 | + | |
| 774 | + | |
| 775 | + | |
| 776 | + | |
| 777 | + | |
| 778 | + | |
| 779 | + | |
| 780 | + | |
| 781 | + | |
| 782 | + | |
| 783 | + | |
| 784 | + | |
| 785 | + | |
| 786 | + | |
| 787 | + | |
| 788 | + | |
| 789 | + | |
| 790 | + | |
| 791 | + | |
| 792 | + | |
| 793 | + | |
| 794 | + | |
| 795 | + | |
| 796 | + | |
| 797 | + | |
| 798 | + | |
| 799 | + | |
| 800 | + | |
| 801 | + | |
| 802 | + | |
| 803 | + | |
| 804 | + | |
| 805 | + | |
| 806 | + | |
| 807 | + | |
| 808 | + | |
| 809 | + | |
| 810 | + | |
| 811 | + | |
0 commit comments