`additionalTypes` on `MetadataPluginConfig` is authorable, documented as THE way a plugin declares a metadata type, and has no reader — a plugin cannot declare a kind at all

[os-zhuang]

Summary

MetadataPluginConfig.additionalTypes is a declared, authorable, documented surface with no consumer anywhere in the repo. A plugin author who follows the published instructions writes it, gets no error, and nothing happens.

Found while measuring #8421 (which needs a live registered-type set at the /meta boundary). It is not that card's defect, so it is filed separately.

Measured

Grepped every file type across packages, apps, examples, docs, content. Every occurrence of additionalTypes is a declaration or a mention — never a read:

site	what it is
packages/spec/src/kernel/metadata-plugin.zod.ts:479	the Zod declaration
packages/spec/authorable-surface/kernel.json:397	kernel/MetadataPluginConfig:additionalTypes — on the authorable surface
packages/spec/authorable-surface.base.json:4507	same, in the anchor
content/docs/plugins/adding-a-metadata-type.mdx (lines 18, 71, 133, 235)	documents it as the plugin's type-declaration path, including a release checklist item
content/docs/references/kernel/metadata-plugin.mdx:98	reference table entry
packages/metadata/src/metadata-manager.ts:2470	a comment claiming the live registry "covers built-ins AND plugin-contributed additionalTypes"
packages/metadata-protocol/src/protocol.ts:4266	a comment claiming the type set "grows later (artifact load, additionalTypes)"

The only production writer of the manager's type registry is packages/metadata/src/plugin.ts:272:

this.manager.setTypeRegistry(DEFAULT_METADATA_TYPE_REGISTRY);

setTypeRegistry (metadata-manager.ts:585) replaces the array outright and is called exactly once outside tests. Nothing ever merges additionalTypes into it.

Measured against the real MetadataManager (vitest, real class, MemoryLoader):

declared count = 27 | live count = 27
getRegisteredTypes() sorted === DEFAULT_METADATA_TYPE_REGISTRY types sorted → true

So typeRegistry in production is exactly DEFAULT_METADATA_TYPE_REGISTRY, always.

Why the two source comments are wrong, not just stale

Both comments above are load-bearing for readers reasoning about the metadata type set — one of them is the doc comment a future author will read when deciding whether a live type check is safe. They assert a growth path that does not exist. (artifact load in the protocol.ts comment is real; additionalTypes is not.)

Corroborating evidence that no kind-declaration channel exists

registerMetadataTypeSchema's own doc comment (packages/spec/src/kernel/metadata-type-schemas.ts) says it plainly:

NOTE — registering a schema alone does not make a type appear in the listing. getMetaTypes() enumerates types from the engine registry and the metadata service, then decorates each with its schema; a type present here but in neither of those is not reached. Register the type as well as its schema.

"Register the type as well" points at additionalTypes — the inert key. #6245 then bound schemas for webhook / connector / sharing_rule without registering the kinds, which is consistent with there being no working channel to register them through.

There is prior art for this exact failure shape on this exact surface: #4212 found these same docs telling plugins to use onInstall, a hook with no invocation site, so plugins "registered nothing and got no error". This is the same silence one level down.

Consequence

A plugin can only get its kind into the live type set as a side effect of registering an item of that kind (SchemaRegistry.registerItem / MetadataManager.register). There is no way to say "this kind exists but has no items yet". That is what blocks #8421: every candidate live registered-type set is an item-population set rather than a declared-kind set.

Disposition

ADR-0049 enforce-or-remove: either wire additionalTypes into setTypeRegistry (making it the real plugin kind-declaration channel, which also unblocks #8421), or remove it and correct the four docs pages plus the two source comments. Not a judgement call this seat should make.

Related: #8421 (blocked by this), #6245, #4212.

---

Generated by Claude Code

[hotlong]

Triage: → needs-user-decision + domain:spec, type Bug (declared ≠ enforced on the published authorable surface: kernel/MetadataPluginConfig:additionalTypes is authorable, documented on four pages as THE plugin kind-declaration path, and read by nothing — measured, plus two load-bearing source comments asserting the phantom growth path).

Routing rationale: the declaration lives in packages/spec/src/kernel/metadata-plugin.zod.ts and both remedies move the spec's accepted/honoured surface — the enforce route makes the key real (capability addition), the remove route retires an authorable key (ADR-0049 / spec-property-retirement). Anything that changes the acceptance surface is domain:spec.

Why the decision box, not the queue: both exits are on the human floor — enforce is a new registration capability (feature class, expands the honoured surface); remove deletes a published, documented capability. Not auto-adjudicable.

Adjudicate jointly with #8421 — its measured report (00:07Z dev report on that card) shows its option B is buildable only if this card goes the enforce route; its recommended option A pairs with either exit here but leaves the silent-typo gap open until a declared-kind channel exists.

Four-prism block:

1. Platform long-term coherence — the status quo is the worst state: a documented authorable key that does nothing, plus two source comments asserting it works. Either exit restores declared = enforced; remove shrinks the surface, enforce grows a real channel that would also make meta-unknown-type-namespace: a /meta type name that is not a plural of anything still mints a namespace — PUT /meta/fieldz/x answers 200 #8421's refusal safe by construction.
2. Measured business pull — zero. No reader anywhere; meta: bind Zod schemas for webhook / connector / sharing_rule WITHOUT registering the kinds — close the unvalidated PUT /meta write hole (#2657 audit, option A) #6245 bound plugin-kind schemas without kind registration, consistent with no plugin ever needing an item-less kind; the only would-be consumer of the enforce route today is meta-unknown-type-namespace: a /meta type name that is not a plural of anything still mints a namespace — PUT /meta/fieldz/x answers 200 #8421's hygiene check. Zero-pull declared surface defaults to remove under ADR-0049.
3. AI-agent error-resistance — the key is a silence trap in exactly the AI-authoring path: write it per the docs, get no error, nothing happens (same shape as Four of the five declared plugin lifecycle hooks are never invoked — and the metadata-type registry docs tell plugins to use one of them #4212's onInstall). Remove makes authoring it a loud schema refusal; enforce makes it work. Both close the trap; keeping it open is the only wrong answer.
4. Startup scope discipline — remove over declare-and-maintain: the enforce route is capability expansion with no current claimant, and every declared key is a permanent obligation.

Recommendation: remove (ADR-0049 route via the spec-property-retirement playbook): retire additionalTypes from MetadataPluginConfig, correct the four docs pages and the two source comments (metadata-manager.ts:2470, protocol.ts:4266), keeping registerMetadataTypeSchema's "register the type as well" note honest about how a kind actually enters the live set. If a plugin later genuinely needs an item-less kind, a declared-kind channel comes back as a designed feature — at which point #8421's option B reopens on solid ground.

---

Generated by Claude Code

[hotlong]

Maintainer ruling (2026-08-14, verbatim: 「同意」, approving item 4 of the six-item ruling list, joint with #8421: 「#8586 remove ＋ #8421 按静态注册表 refuse（联裁）?」): ADR-0049 disposition = remove. Retire additionalTypes from MetadataPluginConfig, correct the 4 docs pages and 2 source comments that advertise it. Measured basis: zero code readers, declared count == live count (27 == 27), no real plugin uses it. Joint consequence for #8421: with the plugin-declared channel removed, the static registry is the total universe of legal metadata kinds, which makes refuse-by-static-registry safe by construction — this card lands first, #8421's refusal follows it. needs-user-decision → pm:queue, target:v17 applied; Seat A (#8667), serial: this card before #8421.

---

Generated by Claude Code