metadata.register('object', ...) applies no namespace-prefix check — the ADR-0028 invariant is enforced caller-by-caller, not at the runtime write path

[os-sam]

Found while working #11061 (the importObject name-override seam). Filed rather than
fixed there: #11061's triage scoped that card to the import seam, and its own body calls
this "a much wider question than this seam". Unassigned — recording, not starting.

What was measured

MetadataManager.register(type, name, data) (packages/metadata/src/metadata-manager.ts)
applies exactly two guards before writing: assertMetadataRegisterContract (name/data
agreement, document shape, canonical type) and the persistence.writable gate. It applies
no namespace check of any kind on register('object', ...) — validateObjectNamespacePrefix
is not called, and no other name gate exists on that path.

The ADR-0028 prefix rule runs at exactly two gates today:

• defineStack() / os validate — compile time (packages/spec/src/stack.zod.ts,
  validateNamespacePrefix).
• the publish pre-flight — packages/metadata-protocol/src/protocol.ts
  (NAMESPACE_PREFIX violations, batch-refused with the validator's own message).

metadata.register is neither, so any runtime caller that persists an object through it
bypasses the declared invariant entirely.

Live exposure, as of #11061's fix

In-tree register('object', ...) callers measured:

• packages/services/service-datasource/src/plugin.ts (persistObject for
  importObject) — was the live bypass; importObject's opts.name override bypasses the namespace prefix and persists an unprefixed federated object #11061's PR closes it at the service seam,
  not at register.
• packages/objectql/src/plugin.ts (two boot-time bridge writes, SchemaRegistry to
  metadata service) — objects that already passed defineStack, so no live violation
  minted there.

So after #11061 the known live exposure is closed, but the invariant remains enforced
caller-by-caller rather than at the write path itself. The next runtime feature that
persists an object via register starts un-gated by default — the same
declared-vs-enforced shape #11061 closed, one layer down.

The question to grade

Should register('object', ...) itself gate the name (making declared = enforced at the
write path), or is the gate deliberately a publish/authoring-time concern with register
kept as the low-level primitive? Considerations pulling in both directions, stated so
triage does not have to rediscover them:

• A gate at register needs a namespace to judge against; MetadataManager has no
  manifest concept (publishPackage's own doc says it indexes by packageId and cannot
  prove a namespace — that is why the publish gate takes namespace as an option).
• A gate at register would also sit on the boot-time bridge writes and any rehydration
  path that reaches it, where refusing a legacy stored row is a different decision than
  refusing a fresh runtime write.

Related: #11061 (the import seam and its ruling that the prefix rule is declared
behavior), #10712 / PR #11059 (the draft half).

[os-zhuang]

Triage: needs-user-decision, domain:engine, Task — where the ADR-0028 namespace invariant is enforced is an architecture/contract-shape question (a register-level gate would also sit on boot bridge writes and rehydration, where refusing a legacy stored row is a different product decision), so this goes to the inbox rather than the queue. Live exposure is closed (#11061); nothing is urgent.

[facets-block]

• 实际业务需求:今天没有任何运行时调用方在铸造违规对象(importObject's opts.name override bypasses the namespace prefix and persists an unprefixed federated object #11061 已关掉唯一活口;objectql 的两处 boot 桥写入都是过了 defineStack 的对象)——风险是「下一个」运行时持久化路径默认不设防,属预防性投入,无现时用户痛感。
• 项目长远合理性:contract-first 倾向在最窄腰部把 declared 变 enforced;但 register 天然缺 namespace 判据(MetadataManager 无 manifest 概念,publish 门为此把 namespace 作为显式参数收进来)——在 register 设门意味着给它引入一个它今天没有的概念,或接受一个只对显式传参的调用生效的半门。
• 防 AI 写代码犯错:caller-by-caller 恰是 AI 最容易漏的形状(新调用方不会记得调 validateObjectNamespacePrefix);写路径设门结构上更稳——但设错门(把 rehydration 的存量行也拒了)是启动级故障,代价不对称。
• 创业阶段不扩散需求:零现时违规 + 设计成本(namespace 判据来源)> 收益;可延后,复发(出现第三个运行时 register 调用方)即重开。

一句话问题:ADR-0028 前缀不变量要不要下沉到 metadata.register('object', …) 写路径本身?

选项	代价
A 现在下沉:给 register 引入 namespace 判据(manifest/显式参数),fresh 运行时写全设防	设计+管线成本;rehydration/boot 桥须显式豁免,豁免面即新的绕行面
B 维持 authoring/publish 两门为准:register 文档化为「不变量线以下的低层原语」,新运行时持久化路径按约定必须自带前缀校验;出现第三个运行时调用方即重开本卡	约定不是机器门;下一个调用方仍可能裸奔一段时间

推荐 B(置信度中高):四轴里业务与创业两轴强烈同向 B,长远轴对 A 的支持被「register 缺判据」的架构事实打折;防 AI 轴的残余风险由「重开条件具名」兜底。裁决格式:回「A」/「B」;B ⇒ 本卡转 S 级文档化任务入队(docblock + 约定行),A ⇒ 需先补 namespace 判据设计再拆卡。

---

Generated by Claude Code

[claude]

Maintainer ruling recorded (atomic four-part write)

Ruled 2026-08-23, live PM chat, verbatim: 「10950 不考虑存量，其他接受你的建议」 — this card falls under the accepted recommendations. Ruled: defer — do not build the register-level gate now. Zero live violations (#11061 closed the only live path), the gate lacks a namespace criterion at that layer, and a wrong gate at rehydration is a boot-level failure with asymmetric cost. Per the standing policy for not-now work, closing not-planned rather than holding without a machine exit. Reopen trigger (recorded, prose): a THIRD runtime caller of metadata.register('object', …) appears, or any runtime persistence path starts minting un-prefixed objects — reopening is free.

---

Generated by Claude Code