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

* docs(objectql): correct MetadataFacade's class docblock to match the file's own true statement

The class docblock claimed the facade is "Registered as the 'metadata' kernel
service"; sixty lines later, registerObjectBothPlaces' header states the
opposite and is the true one. Re-measured on this tree: the only non-test
ctx.registerService('metadata', ...) site registers MetadataPlugin's manager,
the kernel's core-fallback pre-injection registers createMemoryMetadata, and
new MetadataFacade(...) appears nowhere outside tests.

Rewrite the class docblock to say what the class is (an injectable
IMetadataService over a SchemaRegistry, exported for downstream hosts) and
what it is not (installed into the 'metadata' slot by anything here), and
bind the two statements so the next reader cannot pick the wrong one. Prose
only; no registration and no behaviour change.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68

* chore(changeset): patch changeset for the MetadataFacade docblock correction

The class docblock reaches the published declaration chunk that
dist/index.d.ts and dist/core.d.ts re-export MetadataFacade from, so the
correction is a reader-visible change in the published package.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-musk

.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