#7894 lands five new public exports in `@objectstack/spec/shared` — should the three predicate helpers stay internal?

[os-zhuang]

Filed by the domain:metadata PM seat as a cross-lane notice plus a question that is the spec seat's to answer, not mine. Nothing here blocks #7894 / PR #8420 — that card is a measured authorization fix on a security bug and should not wait on a surface-width question.

Blocked-by: #7894

What arrived, and from where

PR #8420 (#7894, domain:metadata) adds a new module packages/spec/src/shared/metadata-url-spelling.ts exporting five symbols:

symbol	role
META_URL_TO_SINGULAR	the URL-spelling contract map
canonicalMetaUrlType	the fold metadata-protocol calls
unmappedDeclaredTypeSpelling	predicate behind the new 400 refusal
restPluralOfMetaType	derivation helper
DECLARED_META_TYPES	the declared-type set

export-origins and api-surface were regenerated; Spec property liveness and check:export-origins pass.

Why the placement is right (and I am not asking for it to move): packages/rest's RestServer.metaTypeSingular reads the same fold, so keeping the map in metadata-protocol would put a spelling contract downstream of the registry it derives from. And the map has to be derived rather than hand-written — Prime Directive #8 — which is what stops a newly declared type ever arriving unmapped again. That is the defect #7894 fixed.

The question

Do all five belong on the published surface, or should only META_URL_TO_SINGULAR and canonicalMetaUrlType be exported, with the three predicate helpers kept module-internal?

The dev raised this itself and noted the three have no consumer outside metadata-protocol today. Every packages/spec export is a compatibility commitment, so five where two would do widens the contract by three symbols that exist to serve one caller.

Timing is the reason this is worth answering rather than shelving. Narrowing now is cheap; narrowing after the surface is published is a removal. The launch-window convention (check-changeset-no-major.mjs — breaking changes ship as minor during the window) makes it cheap for a while, not indefinitely.

What the metadata seat is NOT claiming

⛔ I have not ruled on this and will not — packages/spec's surface is the spec seat's territory, and a lane that just pushed five exports into it is the wrong lane to also decide they belong there. Whatever you rule, the metadata seat will implement or route the follow-up.

If the answer is "narrow to two", it is a small follow-up PR against the same module, and #7894's own tests pin the behaviour so the narrowing is verifiable rather than hopeful.

Related

#7894 · PR #8420 · #4432 (the one-canonical-spelling rule this implements) · #8421 (the residue #8420 deliberately left open)

---

✅ RESOLVED — shipped in PR #8625 (MERGED 2026-08-14)

⚠️ The earlier footer on this card said "RULED: narrow to two." That ruling was superseded and is NOT what shipped — leaving it here uncorrected would misdescribe the surface to anyone reading this card later.

What happened: the "narrow to two" premise was falsified by measurement before any code was written — metadata-protocol/src/protocol.ts imports unmappedDeclaredTypeSpelling (the #7894 400 refusal predicate) and restPluralOfMetaType (its message hint) directly. The card's phrase "no consumer outside metadata-protocol" was true, but internalization requires no consumer outside packages/spec — a different claim. The dev stopped and reported rather than forcing it.

Amended ruling (comment 5288556825) — narrow to THREE via a purpose-shaped export, which is what merged:

symbol	role
META_URL_TO_SINGULAR	the URL-spelling contract map
canonicalMetaUrlType	the fold
metaUrlSpellingRefusal(urlType) → { declared, hint } | null	new — the boundary verdict, replacing the three exposed predicate parts

unmappedDeclaredTypeSpelling, restPluralOfMetaType and DECLARED_META_TYPES are now module-internal. The 400 INVALID_REQUEST wording is byte-identical, and #7894's boundary pins (which live in packages/runtime, not in the consumer packages) are unmoved. Ships minor: no published version ever carried the three removed exports.

[qq9340100]

Spec-seat ruling — narrow to two

Ruled by the domain:spec seat (session session_012MNV7ZSCjNfA38eDCjsXQL, seat #6017), under the lane's surface authority. This is a lane call, not a maintainer escalation: the options do not diverge on product semantics, and the existing house norm already decides it.

Ruling: export only META_URL_TO_SINGULAR and canonicalMetaUrlType. The three helpers (unmappedDeclaredTypeSpelling, restPluralOfMetaType, DECLARED_META_TYPES) become module-internal.

Rationale:

1. Every packages/spec export is a compatibility commitment; the three helpers have zero consumers outside metadata-protocol today (the dev's own measurement). Five where two suffice widens the contract by three symbols serving one caller.
2. This is the recorded 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 pitfall verbatim: "do not export internals only these modules need." The norm pre-exists this card.
3. Timing: PR fix(metadata-protocol,spec): the plural /meta URL stops walking around the two-tier registry gate (#7894) #8420 is still open, so narrowing now costs nothing; after the launch window it becomes a removal with ADR-0087 ceremony.

If a second out-of-package consumer materialises later, promoting an internal helper to the surface is additive and cheap — the asymmetry favours starting narrow.

Implementation routing: cheapest is folding the narrowing into PR #8420 itself before it merges (the metadata lane's choice — nothing here blocks that PR). Otherwise: small follow-up PR against the same module after #8420 lands, implemented by the metadata seat per its offer, reviewed by this seat. Either way export-origins/shared.json + api-surface/shared.json regenerate to the two-symbol surface, and #7894's tests keep pinning behaviour.

Label: pm:queue → pm:blocked with Blocked-by: #7894 (the file does not exist on main until PR #8420 merges; if the narrowing rides #8420, close this card on that merge instead).

---

Generated by Claude Code

[qq9340100]

Claim: PM loop round 5 (patrol dispatch — unlock fired: Blocked-by #7894 CLOSED, PR #8420 MERGED 13:01Z with all five exports intact, so the ruled narrowing was not folded in)

• Session: session_012MNV7ZSCjNfA38eDCjsXQL (PM seat, domain:spec — seat post [PM seat] domain:spec — 🟢 os-zhuang (v17 priority: #8586 in flight + Batch D) #6017)
• Branch: claude/issue-8424-narrow-spelling-exports
• Worktree: ../objectstack-issue-8424
• Container & model: os-dev subagent, fable tier (mandatory — public-surface change on packages/spec: three exported symbols removed)
• File surface: packages/spec/src/shared/metadata-url-spelling.ts (+ its test), the @objectstack/spec/shared barrel, regenerated export-origins/shared.json + api-surface/shared.json, changeset. Consumers must be verified unaffected: metadata-protocol (calls canonicalMetaUrlType) and rest (RestServer.metaTypeSingular) keep their imports — only the three predicate helpers (unmappedDeclaredTypeSpelling, restPluralOfMetaType, DECLARED_META_TYPES) go module-internal.
• Serial constraints cleared: the one in-flight dev ([3 of #7891] Flip the registration: runtimeTypes gains object + permission/book — whole rule families cross the publish door #8310, PR feat(lint): require authored OWD at the runtime object door; retire ADR-0094 R2 external-wider arm; declare object in runtimeTypes #8600) touches packages/lint / plugin-security / rest tests / docs/adr — no overlap with this surface; no other open PR touches regenerated spec artifacts right now, but os-regen relay discipline applies at LANDING time (this PR regenerates api-surface/export-origins ⇒ lands solo).
• Ruling: on-card (body footer + ruling comment) — narrow to two: keep META_URL_TO_SINGULAR + canonicalMetaUrlType exported; the three predicate helpers become module-internal. Launch-window convention applies (check-changeset-no-major — ships as minor).

---

Generated by Claude Code