docs(adr): ADR-0048 §3.4 narrowed — positions, permission sets and capabilities hold one name per deployment (#22198)

Part of #22135

Records the maintainer's ruling Q4 = A on #15196 (ruling record
6050490870, 「15196 Q3 A Q4 A」) in ADR-0048. The security catalog
(positions, permission sets, capabilities) is taken out of §3.4's
cross-package coexistence: each of the three types holds one name per
deployment.

This is the Tier H half of #22135, split from the code PR (#22197) so
the code can land on its own record. It closes nothing: the card is
closed by the code PR. #22135 is not addressed by this PR alone.

## What changed — `docs/adr/0048-cross-package-metadata-collision.md`
only

Additive. The original text is untouched; no existing line is edited.

- **A dated note directly beneath §3.4:** "Narrowed (2026-10-08) — the
security catalog is out of §3.4", with a link to the addendum.
- **A new addendum at the end:** "Addendum (2026-10-08): the security
catalog holds one name per deployment — §3.4 narrowed". It carries:
  - the ruled option's text, verbatim, and the options not taken (B, C);
- N.1, why §3.4's premise (every caller carries its package id) does not
hold for bare-name assignments, with the measurement that motivated the
ruling;
  - N.2, what is refused and who the holders are;
- N.3, what stays as §3.4 has it: same-package reload, every other type,
an environment save, no `OS_METADATA_COLLISION=warn` downgrade;
  - N.4, where it is implemented.

The header's `**Addenda**:` index line is deliberately not edited, to
keep the original text untouched. The note under §3.4 carries the link.

## Gates (at c383221)

`dispatch-gates --commands` derived 19 commands; all 19 were run with
exit codes recorded, and `--ran` reconciles 19/19 with 0 NOT MEASURED.
`check:doc-formula-expressions` first answered PREREQUISITE NOT MET
(exit 3); it passed after `@objectstack/formula` and `@objectstack/lint`
were built.

## 维护者速读(草稿)

### 改了什么
只改了一份架构决策记录 ADR-0048 的文字,没动任何代码。在
§3.4「跨包同名不再报错」那一节下面加了一段带日期的说明,并在文末加了一个附录。内容是把您在 #15196 上的裁决(Q4 选
A)写进去:职位、权限集、能力这三类安全目录,一个部署里一个名字只能有一个持有者。原文一个字都没改。

### 为什么改
ADR-0048 §3.4
当初允许两个包用同一个名字,是因为界面类元数据被调用时总带着「我是哪个包」,系统能分清。但给用户分配职位、给职位挂权限集时,只记名字、不记包。两个包都带同名的「销售经理」,用户到底拿到哪一份权限,就取决于加载顺序。实测确实如此:同一套系统里,职位取后注册的那个包,权限集和能力取先注册的那个。一个应用自带一个叫
`admin_full_access` 的权限集,按名字查到的就是应用自己那份,而不是平台的管理员权限集。您裁定这三类单独收紧,这份 ADR
要跟着记下来,否则 ADR 写着「允许同名」,代码却在拒绝,两边对不上。

### 风险与代价(含回滚)
- 这份 PR 本身只是文档,没有运行时风险。
- 真正的行为变化在配套的代码 PR(#22197):装包或启动时遇到同名会直接报错。仓库里四个示例应用加平台内置名,一共 50
个声明,实测没有一处同名,所以现有示例都能照常启动。已部署环境和应用市场里的包没有测过。
- 回滚:撤销这份 PR 即可,ADR 回到原文;代码 PR 可以分开回滚。

### 席位意见


### 你要做的
请审阅附录的措辞是否准确反映您的裁决,同意就批准(Approve)。这份 PR 属于 Tier H,只能由您批准后落地。

---
_Generated by [Claude
Code](https://claude.ai/code/session_01EUBvqtauTDmHi2ZgY759p2)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

docs/adr/0048-cross-package-metadata-collision.md

@@ -258,6 +258,17 @@ unchanged), and **same-package re-registration** simply overwrites (idempotent
 reload). Authoring-time hygiene — an author shipping two `page/home` in one
 package — stays covered by the `naming/namespace-prefix` lint in `os lint`.
 
+> **Narrowed (2026-10-08) — the security catalog is out of §3.4.** Positions,
+> permission sets and capabilities each hold ONE namespace per deployment: a
+> package whose position, permission set or capability bears a name an installed
+> package, the environment catalog or a built-in already holds is refused at
+> registration, and the error names both holders. §3.4 rests on every caller
+> carrying its package id; an assignment carries a bare position or
+> permission-set name with no package context (ADR-0131 D4), so for these three
+> types a shared name is a real ambiguity, not the disambiguable one described
+> above. Every other type keeps §3.4 as written. See
+> [Addendum (2026-10-08)](#addendum-2026-10-08-the-security-catalog-holds-one-name-per-deployment--34-narrowed).
+
 ### 3.5 Namespace rename-on-install is deferred (non-goal)
 
 Renaming a colliding namespace on install would require rewriting **every**
@@ -749,3 +760,90 @@ Status legend as in §5.
 - **Open-source deployments lose nothing.** They keep the gate that prevents
   corruption; what they do not get is the global authority that would have told
   them earlier.
+
+---
+
+## Addendum (2026-10-08): the security catalog holds one name per deployment — §3.4 narrowed
+
+> **Status of this addendum: Accepted** — it records a maintainer ruling. It
+> **narrows §3.4 for three metadata types and supersedes no other text**: §§1–6
+> and the 2026-08-08 addendum stand verbatim.
+>
+> **Ruling this addendum records** — Q4 on #15196, answered by the maintainer
+> 「15196 Q3 A Q4 A」 (ruling record 6050490870, 2026-10-08); the ruled option's
+> text, verbatim:
+>
+> > The three security catalog types (positions, permission sets, capabilities)
+> > each hold one namespace per deployment. Installing or registering a package
+> > whose position, permission set or capability bears a name an installed
+> > package, the environment catalog or a built-in already holds is refused, the
+> > error naming both holders. ADR-0048 §3.4's retirement of the cross-package
+> > throw is narrowed to leave these three types out: an assignment carries a
+> > bare name with no package context, so for the security catalog a shared name
+> > is a real ambiguity, not the disambiguable one §3.4 describes for UI metadata.
+>
+> Not taken: **B** (assignments carrying `package + name`, which rewrites the
+> ADR-0131 D4 reference syntax and puts a prefix on every assignment) and **C**
+> (resolution by registration order: who holds a permission would depend on load
+> order).
+
+### N.1 Why §3.4's premise does not hold for these three types
+
+§3.4 retires the cross-package throw because "prefer-local always disambiguates
+two different packages": every routed UI surface carries the package id of the
+caller, so two packages' `page/home` never compete for one caller. The security
+catalog has no such caller. A user holds the position `sales_manager`, a position
+binds the permission set `sales_user`, a permission set grants the capability
+`export_data` — each reference is a **bare name** (ADR-0131 D4), stored in
+assignment rows and junction rows with no package coordinate, and resolved by a
+read that takes no package context. Two holders of one name therefore leave the
+grant to whichever definition that read happens to reach first.
+
+That is not hypothetical. Measured before the ruling, on a booted kernel with two
+packages sharing one name per type: the by-name catalog read resolved the
+permission set and the capability to the **first**-registered package and the
+position to the **last**-registered one — two different precedence rules inside
+one catalog. An app declaring a permission set named `admin_full_access` beside
+the platform's own was accepted, and the by-name read answered the app's set.
+
+### N.2 What is refused
+
+A package registration is refused when a position, permission set or capability
+it declares names something another holder already holds. The holders:
+
+- **an installed package** — including a disabled one, which is still installed
+  and still holds its names;
+- **the environment catalog** — an item authored in this environment rather than
+  shipped by a package;
+- **a built-in** — the platform's built-in identity positions and audience
+  anchors, and its curated capabilities. The platform's permission sets are
+  declared by the security plugin's own package and are held by it like any
+  other package's.
+
+The error names both holders and carries an ADR-0112 envelope (`422`, with the
+code the §3.2 namespace gate already uses): the condition is the same one — a
+name in a deployment-wide namespace is already taken — and so is the remedy:
+rename, or uninstall the other holder.
+
+### N.3 What stays as §3.4 has it
+
+- **Same-package re-registration** — an idempotent reload, a re-install, a hot
+  reload — is one holder, not two, and simply overwrites.
+- **Every other metadata type** keeps §3.4's coexistence: two packages' `page/home`
+  still coexist under distinct composite keys.
+- **A write with no package provenance** — an environment save over a
+  package-held name, which is how every `sys_metadata` hydration arrives — stays
+  under ADR-0005 overlay precedence. The ruling covers installing or registering a
+  package, not a metadata author's save; that path is unchanged by this addendum.
+- **No downgrade.** `OS_METADATA_COLLISION=warn` softens the §3.2 namespace gate
+  only; no ruling extends it to this refusal.
+
+### N.4 Where it is implemented
+
+`@objectstack/objectql`: the rule and its holders in `security-catalog-namespace.ts`;
+the package door in `SchemaRegistry.installPackage` (ahead of every mutation, so a
+refused package leaves no record) and the item seam in `SchemaRegistry.registerItem`
+for a package-bound registration that reaches the registry directly. Every package
+registration reaches the package door before any in-memory registrar runs, so the
+boot of a conflicting composition — an artifact boot included — is refused in its
+first phase.