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

[os-zhuang]

Summary

#7894 closed the case where a plural URL spelling of a declared metadata type walked around the two-tier registry gate. This is the residue it deliberately left, filed so it is findable by someone who is not reading PR #8420.

At the /meta boundary a type name that is neither a declared registry type nor any known plural spelling — fieldz, objectt, any typo — is still treated as a plugin-registered type, which every authorization gate is permissive toward by construction. The write is accepted and a sys_metadata row is persisted under type='fieldz': a namespace for a metadata type that does not exist and never will.

PUT /api/v1/meta/fieldz/showcase_task.title   → 200, row persisted with type='fieldz'

How this differs from #7894 — narrower, and NOT an authorization bypass

Worth stating precisely, because the surface looks identical and the severity is not:

• meta-plural-url-bypass: PUT /meta/fields/<name> walks around the whole two-tier registry gate — 4 registry types have no entry in PLURAL_TO_SINGULAR #7894 was an authorization bypass. fields is a spelling of field, a type the registry declares allowOrgOverride: false. The plural URL shadowed a locked type, so the plural spelling was a door around the singular spelling's lock — /meta/field/… answered 403 NOT_OVERRIDABLE while /meta/fields/… answered 200.
• This one shadows nothing. fieldz is not a spelling of any declared type, so there is no lock being walked around and no second namespace for an existing item. Nothing is served from type='fieldz', and no gate is being evaded.

What it is is the same second-namespace class #4432 was filed about: a row keyed by a type nothing reads, minted because the boundary forwarded a name it could not honour instead of refusing it. It is accumulation of unreachable rows and a silently-accepted caller error, not an escalation.

Related: this is also what makes a metadata-type typo silent. An author or an AI writing PUT /meta/fieldz/... gets 200 {"success":true} and no indication the type is not real.

Why #7894 did not close it

The refusal shipped in #7894 is deliberately static, per the maintainer ruling of 2026-08-12 on refusing at the boundary: it fires only when a spelling's singular is a type present in DEFAULT_METADATA_TYPE_REGISTRY. That is what makes the positive control hold by construction — a genuinely plugin-registered runtime kind can never trip it, whatever it is named and whenever it registers.

fieldz does not singularize to any declared type, so by that rule it is indistinguishable from a plugin kind and takes the plugin path.

Closing this needs the live registered-type set at the boundary — "is this type registered right now?" rather than "is this a spelling of something declared?" — and that has a materially different risk profile:

• canonicalMetaType / canonicalizeMetaRequestType are pure module-level functions today, with no access to live state; a live lookup means threading the registry through the boundary.
• The failure mode is worse than the defect. A live check that runs before a plugin has registered its kind refuses a legitimate type, turning a hygiene fix into a plugin-registration outage. The ordering between plugin registration and the first /meta write would become load-bearing where it currently is not.
• It needs a decision on what "registered" means for a type a plugin registers lazily, and on whether the refusal is per-request or per-boot.

So the remedy is a different change with a different shape, not a widening of the static predicate.

Pinned, not silent

The limitation is asserted rather than merely described, so it cannot go quiet:

• packages/spec/src/shared/metadata-url-spelling.test.ts — case "documents its residue rather than pretending to be total", asserting unmappedDeclaredTypeSpelling('fieldz') is null.
• The reasoning lives in the doc comment of unmappedDeclaredTypeSpelling in packages/spec/src/shared/metadata-url-spelling.ts, under the heading "Known residue, deliberately not closed here".

⚠️ If this card is fixed, that test case inverts — it currently asserts the gap. Flip it rather than deleting it, the way #7894 flipped the case #7743 left behind.

Source

Left as documented residue by #7894 / PR #8420; filed at the PM's request so a known-unfixed gap has a card as well as a pin.

[os-zhuang]

Claiming this card.

• Session: session_012WMpuAfA2KSdDjGF6tm1bH
• Branch: claude/issue-8421-unknown-meta-type
• protocol.ts regions: none planned. If that changes I will amend this comment before editing (a sibling card holds the publishPackageDrafts region).

Plan of record, per the dispatch: measure first. The card names two undecided things (what "registered" means for a lazily-registered plugin kind; per-request vs per-boot refusal) and one hazard (a live check running before plugin registration refuses a legitimate type). I will measure whether the registry exposes a live registered-type set at the /meta boundary and whether the ordering hazard is real, and will stop at the fork and report rather than pick per-request vs per-boot.

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

STOPPED AT THE FORK — measured, no PR

The card asks for the live registered-type set at the /meta boundary. Measured answer: it does not exist. What exists is an item-population set, and a refusal built on it would refuse the first runtime create of every legitimate plugin kind. The ordering hazard the card feared is real, and it is worse than ordering — it is steady-state, so there is no ordering to pin.

No code changed. The residue pin is untouched and green.

The three candidate live sets, all disqualified

1. listLiveMetadataTypes() (packages/metadata-protocol/src/protocol.ts:4274) — reachable at the boundary. It is a private method on the same class that hosts all six /meta entry points, so threading it into canonicalizeMetaRequestType is mechanically trivial. That is the only good news. It is the union of two item-population sets:

• SchemaRegistry.getRegisteredTypes() = Array.from(this.metadata.keys()) (packages/objectql/src/registry.ts:3138). this.metadata gains a key only in registerItem (2513-2517).
• MetadataManager.getRegisteredTypes() = typeRegistry union this.registry.keys() (packages/metadata/src/metadata-manager.ts:2446); that map gains a key only when an item is stored.

2. MetadataManager.typeRegistry — a genuine declared-kind set, but in production it is exactly DEFAULT_METADATA_TYPE_REGISTRY (measured 27 declared / 27 live, set-equal). setTypeRegistry is called once outside tests, at packages/metadata/src/plugin.ts:272, and additionalTypes has no reader anywhere. So it is identical to what #7894's static rule already consults — it adds nothing. Filed separately as #8586.

3. listMetadataTypeSchemaTypes() — contains none of the six plugin kinds, and misses declared external_catalog entirely.

The hazard is steady-state, not a boot race

M3b  listLiveMetadataTypes()          = ["object","field","view"]   → theme ABSENT
M3d  saveMetaItem({type:'theme', …})  = NONE (accepted), row type=theme

theme is a legitimate plugin kind. With zero items it is absent from the live set — and PUT /meta/theme/dark is accepted today, because that create is the first theme item. A live check refuses precisely the operation the plugin path exists to serve. Pinning "plugins register before HTTP serves" does not help: a plugin that ships zero items of its kind never enters the set at any moment.

It is also bidirectional, and the two halves disagree with each other:

M1c  SchemaRegistry  after last unregisterItem → ["theme"]  (STICKY, key never deleted)
M2c  MetadataManager after last unregister     → theme GONE (SHRINKS)

MetadataManager deletes the type key when its store empties, at metadata-manager.ts:1385-1387 and again at 2871 (invalidateForForeignWrite — so another node's delete can do it). Delete the last item of a kind and re-create it, and a live check refuses the re-create. The sticky-vs-shrinking asymmetry between the two union halves is a latent inconsistency in its own right, unrelated to this card.

So the card's two questions are downstream of a third

The card names two undecided things — what "registered" means for a lazily-registered kind, and per-request vs per-boot. Measurement says neither is answerable as posed, because there is no declared-kind registry to consult at either moment. Per-request and per-boot are two sampling times for a set that is wrong at every time. The prior question is:

Should a plugin be able to declare a metadata kind without registering an item of it?

Today it cannot (#8586). Until it can, "is this type registered right now?" can only mean "does this type have at least one item right now?", which is not the question the boundary needs to ask.

Options, with costs

A — leave it; keep the residue pinned. Cost: the silent typo stays (PUT /meta/fieldz/... answers 200 {"success":true}), and unreachable rows keep accumulating. Zero risk.

B — make a declared-kind channel real first (wire additionalTypes, or add an explicit registerMetadataKind()), then refuse a type that is in neither the static registry nor the plugin-declared set. This is the only version where the refusal is safe by construction — the property #7894's ruling bought and that this card must not spend. Cost: a new registration capability, migration for the six kinds that today exist only as manifest spellings, and per-request/per-boot still to be decided (but then safely, since a declared set does not depend on item population). Really #8586's card first, not this one.

C — live check against listLiveMetadataTypes() as it stands. Disqualified by measurement above: breaks first-create and delete-then-recreate. This is the option the card warned about, and it is worse than it looks — not a startup window, a permanent hole.

On the three axes, for B:

• Real business need — thin, measured. fieldz mints a row nothing reads; I found no caller, no example app, and no deployment that depends on refusing it. The one real harm is the silent typo, which is a correctness-of-authoring concern rather than a business scenario with a claimant. Startup focus (2026-08-04, core capability first): B is capability expansion whose only current consumer would be this hygiene check. That argues A now, B when a plugin actually needs an item-less kind.
• Long-term soundness — favours B, mildly. B is the contract-first shape (declared = enforced). But A is not free either: it leaves a documented, authorable, inert key sitting on the published surface (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 #8586), which is its own accumulating cost. C is a heuristic wearing a guarantee's clothes and should not ship at any price.
• Making AI-written metadata hard to get wrong — favours closing it, but only via B. The silent 200 on a metadata-type typo is exactly where AI-generated errors hide and multiply, so this axis pulls hardest toward a fix. But note C inverts on this axis: it would make AI-authored plugins fail at registration instead, moving the failure rather than removing it.

My recommendation: A for now, and treat #8586 as the real prerequisite — but I am explicitly not choosing per-request vs per-boot, and B is a live option if the typo silence is judged worth the capability. The axes genuinely conflict here (need says wait, AI-safety says close), which is why this is yours.

Positive control — mandatory, and it holds

• M3d: a legitimately plugin-registered kind (theme) with zero items is accepted today; M3b shows it is absent from the live set. Together these are the demonstration that a live check would refuse it — the exact outage the card names.
• The existing meta-plural-url-bypass: PUT /meta/fields/<name> walks around the whole two-tier registry gate — 4 registry types have no entry in PLURAL_TO_SINGULAR #7894 control, re-run untouched: "POSITIVE CONTROL — cannot refuse a plugin kind, whatever it is named" — green, in a 14/14 suite.

Prediction vs measurement

11 probes predicted before running; 11 matched, zero divergences. M1a [] / M1b ["theme"] / M1c sticky; M2a 27-and-no-theme / M2b present / M2c gone / M2d set-equal; M3a defect reproduces / M3b absent / M3c present / M3d accepted.

Divergence to declare honestly: for the M4 batch I pre-predicted only the headline ("the schema channel will not cover plugin kinds" — confirmed, 0 of 6). Two sub-results were not predicted and are new information: external_catalog is a declared type with no schema at all (M4d), and listUnregisteredKindSchemaTypes() carries only 3 of the 6 plugin kinds — connector, sharing_rule, webhook, matching #6245's scope and omitting theme, analytics_cube, rag_pipeline (M4e).

How I confirmed the harness is not vacuous

• M3a reproduces the real defect end-to-end — saveMetaItem({type:'fieldz'}) accepted, row persisted with type='fieldz'. A harness that never reached the boundary would persist nothing.
• Every probe has an opposite-direction twin that actually moves: absent → present → absent across M1a/b/c, M2a/b/c and M3b/c. A constant-true assertion cannot produce that pattern.
• The runner demonstrably fails: my first objectql run errored out on an unbuilt @objectstack/metadata-protocol dependency before I built the closure — execution proven, not a silent pass.
• Measurements ran against the real SchemaRegistry, real MetadataManager and the real protocol write path, not mocks of the thing under test.

Flip, do not delete

Not applicable — I closed nothing. unmappedDeclaredTypeSpelling('fieldz') still returns null, the case "documents its residue rather than pretending to be total" stays exactly as written, and the "Known residue, deliberately not closed here" doc comment in metadata-url-spelling.ts remains accurate. #7894's static predicate was not widened or touched.

Things you did not ask about

1. 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 #8586 filed (unassigned, unlabelled, searched for duplicates first — none open): additionalTypes is authorable, on the published surface, documented across four docs pages as the plugin type-declaration path, and read by nothing. It is the direct blocker for option B.
2. Two source comments are wrong, both load-bearing for anyone reasoning about this exact question: metadata-manager.ts:2470 claims the live registry covers "plugin-contributed additionalTypes", and protocol.ts:4266 claims the type set "grows later (artifact load, additionalTypes)". The artifact load half is real; the additionalTypes half is not. Captured in 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 #8586 rather than fixed here, since touching them is a code change this card should not ship.
3. The sticky-vs-shrinking asymmetry between SchemaRegistry (never drops a kind key) and MetadataManager (drops it when the store empties, including on a foreign write) is a pre-existing inconsistency inside listLiveMetadataTypes(). It bites nothing today because the union is only used for a listing, but it would become load-bearing under option B or C. Not filed separately — it is only meaningful in the context of 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 #8586's disposition, and I did not want to scatter it.

{
  "issue": 8421,
  "status": "needs_decision",
  "branch": "claude/issue-8421-unknown-meta-type (created, no commits — nothing to push)",
  "pr": null,
  "premise_still_valid": true,
  "summary": "Stopped at the fork the card names, as instructed, with the fork sharpened by measurement. The premise holds exactly: PUT /meta/fieldz/x is still accepted and still mints a sys_metadata row under type='fieldz' (reproduced end-to-end against the real protocol write path). But the live registered-type set the card says a fix needs DOES NOT EXIST. All three candidates are disqualified by measurement: listLiveMetadataTypes() is an item-population set (a kind is present only if it has at least one registered item), MetadataManager.typeRegistry is exactly DEFAULT_METADATA_TYPE_REGISTRY in production because additionalTypes has no reader, and listMetadataTypeSchemaTypes() contains none of the six plugin kinds. The ordering hazard is therefore real AND worse than the card feared: it is steady-state rather than a boot race, so there is no ordering to pin. A live check would refuse PUT /meta/theme/dark whenever theme has zero items — which is the first runtime create, the very operation the plugin path exists to serve — and MetadataManager additionally DELETES a kind key when its last item goes, so delete-then-recreate breaks too. Consequently the card's two named questions (what 'registered' means for a lazy kind; per-request vs per-boot) are both unanswerable as posed: they are two sampling times for a set that is wrong at every time. The prior question is whether a plugin should be able to declare a kind without registering an item, which today it cannot — filed as #8586. No code written, no PR opened, #7894's static predicate untouched, the residue pin left asserting the gap.",
  "tests": "No product code changed, so nothing was owed beyond measurement and a regression check of the pin I would have had to flip. Measurement harnesses (three temporary vitest files, since deleted; git status clean) ran against the REAL SchemaRegistry, the REAL MetadataManager and the REAL protocol write path. M1 (objectql, 3/3): fresh getRegisteredTypes() = [] ; after registerItem('theme',…) = [\"theme\"] ; after unregisterItem = [\"theme\"] with listItems('theme') = [] — sticky. M2 (metadata, 4/4): declared count 27, has field=true has theme=false ; after register theme=true ; after unregister theme=false — shrinks ; live set set-equal to DEFAULT_METADATA_TYPE_REGISTRY. M3 (metadata-protocol, 4/4): saveMetaItem type='fieldz' → error NONE (accepted), rows [{type:'fieldz',name:'showcase_task.title'}] ; listLiveMetadataTypes() = [\"object\",\"field\",\"view\"] with theme absent ; = [\"object\",\"theme\"] once one theme item exists ; saveMetaItem type='theme' → NONE (accepted) with row type=theme. M4 (built spec dist): 27 declared vs 26 schema types, 0 of 6 plugin kinds in the schema set, external_catalog missing a schema, listUnregisteredKindSchemaTypes() = [\"connector\",\"sharing_rule\",\"webhook\"]. Regression check: the full #7894 pin suite, packages/spec metadata-url-spelling, 14/14 PASS — including both the residue case asserting unmappedDeclaredTypeSpelling('fieldz') is null and the POSITIVE CONTROL 'cannot refuse a plugin kind, whatever it is named'. Build discipline: built the metadata-protocol closure, then hit the documented fresh-worktree trap (objectql's own dependency @objectstack/metadata-protocol was unbuilt, producing a resolve error that reads like a code break) and built the objectql closure before re-running — that failure doubles as proof the runner really executes. All heavy runs serialized under flock /tmp/os-heavy-verify.lock with --max-old-space-size=4096 and --maxWorkers=2. Gates: none run, and none owed — the diff is empty. Worktree removed unforced after a clean git status.",
  "open_questions": [
    {
      "question": "The card asks for the live registered-type set at the /meta boundary. Measured: it does not exist. listLiveMetadataTypes() is an ITEM-POPULATION set, not a declared-kind set — a legitimate plugin kind with zero items is absent from it permanently, not transiently. So a live refusal breaks the FIRST runtime create of every plugin kind (measured: theme absent from the live set, yet PUT /meta/theme/dark accepted today), and MetadataManager's key-deletion on empty (metadata-manager.ts:1385-1387, 2871) additionally breaks delete-then-recreate. There is no ordering to pin, so per-request vs per-boot cannot be chosen — both sample a set that is wrong at every moment. Which route?",
      "options": [
        "A — leave it; keep the residue pinned. The silent typo stays (200 {\"success\":true} on PUT /meta/fieldz/...) and unreachable rows keep accruing. Zero risk. Leaves the inert authorable key of #8586 in place as its own cost.",
        "B — make a declared-kind channel real FIRST (wire additionalTypes, or add registerMetadataKind()), then refuse a type in neither the static registry nor the plugin-declared set. The only route where the refusal is safe BY CONSTRUCTION, preserving what #7894's ruling bought. Cost: new registration capability, migration for the six kinds that exist today only as manifest spellings, and per-request vs per-boot still to decide (but then safely). Prerequisite is #8586, not this card.",
        "C — live check against listLiveMetadataTypes() as it stands. DISQUALIFIED by measurement: refuses legitimate first-creates and re-creates. This is the outage the card predicted, and it is permanent rather than a startup window."
      ],
      "recommendation": "A for now, with #8586 as the real prerequisite for ever doing B; C should not ship at any price. Three axes, and they genuinely conflict — which is why I am not deciding. REAL BUSINESS NEED: thin and measured — nothing reads a type='fieldz' row, I found no caller, example app or deployment depending on the refusal, and the only real harm is the silent typo, which has no claimant. Under the 2026-08-04 startup-focus principle, B is capability expansion whose sole consumer today would be this hygiene check, so it is handled implementation-first and waits for a plugin that actually needs an item-less kind. LONG-TERM SOUNDNESS: mildly favours B — declared-equals-enforced is the contract-first shape — but A is not free either, since it leaves a documented, authorable, inert key on the published surface (#8586). C is a heuristic dressed as a guarantee and is unsound at any horizon. AI-AUTHORING SAFETY: this axis pulls hardest toward closing the gap, because a silent 200 on a metadata-type typo is exactly where AI-generated errors hide and multiply — but note C INVERTS on it, making AI-authored plugins fail at registration instead, which moves the failure rather than removing it. So only B closes it without refusing legitimate kinds. Business need says wait; AI-safety says close; soundness says if you close it, close it via B. That trade-off is the maintainer's to resolve, and I am explicitly not choosing per-request vs per-boot."
    },
    {
      "question": "Not asked about, and load-bearing for anyone re-deciding this later: two source comments assert a growth path that does not exist. metadata-manager.ts:2470 says the live registry covers 'plugin-contributed additionalTypes'; protocol.ts:4266 says the type set 'grows later (artifact load, additionalTypes)'. The artifact-load half is real; the additionalTypes half is not.",
      "options": [
        "Left both unchanged and captured them in #8586 — correcting them is a code change this card should not ship while it is stopping at a fork.",
        "Say the word and I will fix the two comments as a docs-only follow-up."
      ],
      "recommendation": "Leave as filed. They matter because protocol.ts:4266 is precisely the comment a future author reads when judging whether a live type check is safe — it is one of the reasons this card looked more tractable than it is."
    }
  ],
  "out_of_scope_findings": [
    "filed as #8586: MetadataPluginConfig.additionalTypes is authorable, on the published surface, documented across four docs pages as THE plugin type-declaration path, and read by nothing — so a plugin cannot declare a metadata kind at all, only register an item of one. Direct blocker for option B above. Corroborated by registerMetadataTypeSchema's own doc comment ('Register the type as well as its schema') pointing at the inert key, and by the same-shape precedent in #4212.",
    "NOT filed separately, deliberately: SchemaRegistry never deletes a kind key once created while MetadataManager deletes it when the store empties, so the two halves of listLiveMetadataTypes() disagree about whether a kind survives its last item. Harmless today (the union only feeds a listing) but load-bearing under option B or C. It is only meaningful in the context of #8586's disposition, so I recorded it there and in this report rather than scattering a third card."
  ]
}

---

Generated by Claude Code

---

Generated by Claude Code