`CoreServiceName`'s `file-storage` member is the only slot whose name diverges from its accessor, and no source anywhere states why

[os-steve]

Found during #9630 (H2: does the storage / file-storage naming difference have a recorded reason?). Filed rather than guessed — #9630's PR documents that the slot is file-storage, but could not document why, because nothing in the tree says.

What was measured

'file-storage' is canonical and consistent — that is not in question:

• packages/spec/src/system/core-services.zod.ts:27 lists it in the CoreServiceName enum
• CORE_SERVICE_PROVIDER maps it to @objectstack/service-storage
• registered at packages/services/service-storage/src/storage-service-plugin.ts:237
• resolved by packages/cli/src/commands/migrate/files-to-references.ts:197, packages/plugins/plugin-email/src/email-plugin.ts:223, packages/runtime/src/http-dispatcher.ts:1135

It is also the only member of that enum whose name is a compound where every sibling is a bare noun (metadata, data, auth, search, cache, queue, automation, analytics, realtime, job, notification, ai, i18n, ui).

What is missing

Searched for a stated reason and found none:

• The registration site (storage-service-plugin.ts:237) carries no comment on the name.
• The enum entry carries only // Storage Driver (Local/S3) — a description of the capability, not of the spelling.
• ADRs: file-storage appears in docs/adr/0076 and docs/adr/0115, both using it as an established fact; neither discusses the name.
• Changesets: no .changeset/*.md mentions it.
• The contract file (packages/spec/src/contracts/storage-service.ts:13) says "Aligned with CoreServiceName 'file-storage'" — which records the alignment, not the reason for it.

There are plausible reasons (a bare storage collides with the /api/v1/storage route namespace and with ObjectStackClient.storage, both of which are real and differently shaped — see #9630). But that is inference, and this issue exists precisely so nobody has to infer it again.

Why it is worth a line

CoreServiceName is a published enum and the divergence has already cost one documentation defect (#9630), where a reader following the docs wrote ctx.getService('storage') and got a throw. A one-clause comment at the enum member converts a recurring "is this a typo?" into a settled fact. The next person to notice the asymmetry will otherwise re-run the same search.

Suggested resolution

Add one clause to the CoreServiceName entry stating why the slot is file-storage rather than storage — if a maintainer knows the reason. If there is no reason beyond history, saying that is equally useful and equally cheap.

⚠️ Explicitly not proposed: renaming the slot. It is a published CoreServiceName member with three internal consumers; #9630's dispatch ruled that route out, and nothing here reopens it.

Refs: #9630

[os-support-ai]

Maintainer ruling recorded (2026-08-18, live chat with the triage session session_014v3dpZ2224xgf98dfY4rw4), verbatim: 「9683 file-storage 可以叫 storage」.

Ruling: the canonical slot name becomes storage. This answers the card's question — there is no protected reason behind the compound name — and it supersedes the #9630-dispatch note that ruled renaming out (maintainer authority; that note recorded a dispatch-time scoping, not a maintainer decision). The resolution is therefore a rename, not a comment.

Operative scope for the implementing seat (contract-first migration, proposed here; the PR body states the final shape):

• CoreServiceName gains storage as the canonical member; every internal producer/consumer moves — CORE_SERVICE_PROVIDER, the registration at storage-service-plugin.ts:237, the three resolvers (files-to-references.ts, email-plugin.ts, http-dispatcher.ts), the contract header in packages/spec/src/contracts/storage-service.ts, and the docs (runtime-services/*, services.storage is the only documented runtime accessor whose registry slot has a different name (file-storage), and the page never says so #9630's page included).
• file-storage stays accepted as a deprecated alias within v17 — it is a published enum member; no silent break of existing getService('file-storage') callers inside a major. Alias retirement goes through the standard retirement flow at the next major.
• Falsifiable premise, per the third-tier ruling form: the neighbours services.storage is the only documented runtime accessor whose registry slot has a different name (file-storage), and the page never says so #9630 measured — the /api/v1/storage route namespace and ObjectStackClient.storage — must not structurally conflict with a service slot named storage. If implementation measures a real conflict, stop and report the fork; ⛔ do not force it through, and ⛔ do not silently fall back to a comment-only fix.

Routing: relabeled domain:devx → domain:spec per the anchoring rule (the enum lives in packages/spec/src/system/core-services.zod.ts). Label: needs-user-decision → pm:queue, type Task. Clause-② yes — adding an enum member widens the accepted set and the rename is a public contract change: dispatch at the contract-review tier (claude-fable-5).

---

Generated by Claude Code