From 169d8df388b49f222554b0e8907788dfc887566d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 2 Sep 2026 09:45:29 +0000 Subject: [PATCH 1/2] 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 Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68 --- packages/objectql/src/metadata-facade.ts | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/packages/objectql/src/metadata-facade.ts b/packages/objectql/src/metadata-facade.ts index 48d6df63d0..082ea91ed1 100644 --- a/packages/objectql/src/metadata-facade.ts +++ b/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 From 329608eb04d46998547bdae157c5767ca4389873 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 2 Sep 2026 09:58:52 +0000 Subject: [PATCH 2/2] 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 Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68 --- .changeset/metadata-facade-docblock.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .changeset/metadata-facade-docblock.md diff --git a/.changeset/metadata-facade-docblock.md b/.changeset/metadata-facade-docblock.md new file mode 100644 index 0000000000..42bbac6bf9 --- /dev/null +++ b/.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.