docs(objectql): correct MetadataFacade's class docblock — it is not the installed 'metadata' kernel service

.changeset/metadata-facade-docblock.md

@@ -0,0 +1,23 @@
+---
+"@objectstack/objectql": patch
+---
+
+docs(objectql): correct `MetadataFacade`'s class docblock — it is not the installed `'metadata'` kernel service (#14019)
+
+The class docblock claimed `MetadataFacade` is "Registered as the 'metadata'
+kernel service". Sixty lines down the same file, `registerObjectBothPlaces`'
+header states the opposite — nothing installs a `MetadataFacade` into that
+slot — and the second statement is the true one. This docblock ships to
+consumers inside the package's declaration files, so the false half was
+readable from an editor's hover on an imported `MetadataFacade`.
+
+Re-measured on the current tree: the only non-test `registerService('metadata',
+…)` site registers `MetadataPlugin`'s own manager; the kernel's core-fallback
+pre-injection registers `createMemoryMetadata`; and `new MetadataFacade(...)`
+appears nowhere outside tests.
+
+The docblock now says what the class is — an injectable `IMetadataService` over
+a `SchemaRegistry`, exported from this package's root and `core` entrypoints
+for a downstream host that chooses to install it — and what it is not, in the
+same voice as the header that already said so. Prose only: no registration, no
+behaviour change, no API change.

packages/objectql/src/metadata-facade.ts

@@ -66,12 +66,25 @@ function toKeyedDefinition(type: string, name: string, data: unknown): any {
 /**
  * MetadataFacade
  *
- * Provides a clean, injectable interface over SchemaRegistry.
- * Registered as the 'metadata' kernel service to eliminate
- * downstream packages needing to manually wrap SchemaRegistry.
+ * A clean, injectable `IMetadataService` over a `SchemaRegistry`, so a host
+ * does not have to wrap `SchemaRegistry` by hand. Implements the async
+ * `IMetadataService` interface (`@objectstack/spec/contracts`) by delegating
+ * to `SchemaRegistry` (in-memory) with Promise wrappers.
  *
- * Implements the async IMetadataService interface.
- * Internally delegates to SchemaRegistry (in-memory) with Promise wrappers.
+ * ⛔ **Nothing in this repository installs a `MetadataFacade` into the
+ * `'metadata'` kernel slot — this class is not that service.** In-tree the
+ * slot is filled by `MetadataPlugin`'s own manager
+ * (`ctx.registerService('metadata', this.manager)`, `@objectstack/metadata`)
+ * or, when no plugin provides one, by the kernel's core fallback
+ * `createMemoryMetadata` (`CORE_FALLBACK_FACTORIES.metadata`,
+ * `@objectstack/core`). This class exists for DOWNSTREAM hosts: it is
+ * exported from this package's root and `core` entrypoints, and a host that
+ * wants a `SchemaRegistry`-backed metadata service installs it itself. An
+ * earlier revision of this docblock asserted the opposite; that sentence, not
+ * any code, is the likely source of #13331's premise.
+ * {@link registerObjectBothPlaces}'s header states the same fact with the
+ * fuller account of what being uninstalled in-tree costs — the two are meant
+ * to be read as one voice, so change both or neither.
  *
  * Each facade is bound to a specific SchemaRegistry instance — passed in the
  * constructor — so that multi-kernel servers can give every kernel its own