@bymax-one/nest-core 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -11,6 +11,89 @@ heading here.
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-09-05
+
+A library contributing an OpenAPI component under a name the application already
+declared had its entry discarded, and neither side could tell. The document
+validated, the served output looked exactly as it would have had nothing been
+offered, and the contributing library received no signal at all — so the failure
+was indistinguishable from success at both ends.
+
+Two changes, and they are independent: an empty placeholder no longer counts as a
+declaration, and every genuine collision is now reported.
+
+**This patch adds public surface**, which a patch number cannot tell you:
+`discarded` on `OpenApiMountOutcome`, and the `DiscardedComponent` type it holds.
+Both are additive and nothing is removed or renamed, so the digit stays at a
+patch under this project's versioning policy — which means this paragraph, rather
+than the version, is what says there is something new to look for.
+
+**Apply to a derived backend:** nothing is required, and no served document loses
+anything it carried. A schema the application declares with a shape of its own
+still wins, exactly as before. What changes is that a schema present only as
+`{"type":"object","properties":{}}` — which `@nestjs/swagger` emits for every DTO
+in a package built without its plugin — is now filled from the contribution
+rather than preferred over it. Read `discarded` on the `OpenApiMountOutcome` to
+see what a contributor offered and did not place; the boot log reports the same
+entries.
+
+### Added
+
+- **`discarded` on `OpenApiMountOutcome`, and the `DiscardedComponent` type.**
+  Lists every contributed component entry the document already declared with a
+  shape of its own, naming the contributor, the member and the entry. Present
+  whenever the document mounted, empty when every contribution was placed — an
+  empty array reports that the merge looked and found none, which absence would
+  confuse with not having looked.
+
+  Carries the contributor's label because a collision is only actionable if you
+  know whose entry lost: an application with several contributing libraries would
+  otherwise be told a name was dropped without being told by whom.
+
+  A warning reports the same entries on the way up, elided into a count on the
+  same reasoning as the unsecured-operation line beside it — a library contributing a
+  schema per DTO turns one collision into a hundred, and the version that prints
+  them all is the one an operator learns to skip.
+
+### Changed
+
+- **A schema that describes no shape no longer counts as a declaration.** The
+  merge still prefers what the document carries: a consumer authored theirs on
+  purpose, and a library silently overwriting it is the worse defect wearing the
+  other sign. But `@nestjs/swagger` emits `{"type":"object","properties":{}}` for
+  every DTO in a package built without its plugin, so the name is never actually
+  missing and a contributed schema under it would never be written. The more
+  correct the library's own schema, the more completely it was discarded, because
+  a correct schema and an empty one collide on the same key.
+
+  This is the rule `mergeResponses` already applied to responses, arriving
+  through a different placeholder — a `200` carrying a description and no
+  `content` occupies its status the same way. Filling one in is additive: it
+  constrains nothing before and describes a shape after.
+
+  The test is deliberately narrow. `type` must be absent or `object`, because
+  `{"type":"string"}` carries no properties and is nonetheless complete;
+  reading "no properties" as "no shape" would discard a real schema, which is
+  the failure this path exists to prevent. An empty `required` and a
+  `description` do not change that; any other keyword, or a single property,
+  makes the entry a declaration. A description the document
+  wrote survives being filled in, the same carve-out `mergeResponses` makes.
+
+  The carve-out applies to `schemas` alone. A parameter carries `name` and `in`
+  rather than `properties`, so a schema-shaped emptiness test reads every one of
+  them as a placeholder and would let a contributor overwrite one the consumer
+  wrote — the precedence failure inverted, arriving through the fix for the
+  other one.
+
+  This package's own catalogue, under `openapi.includeCoreSchemas`, is placed by
+  the same rule and before any library. A placeholder under a catalogue name is
+  filled with the package's definition, so a library offering that name meets a
+  declaration and is reported rather than outranking the package.
+
+- **`fastify` and `@nestjs/platform-fastify` devDependency floors raised to
+  `^5.12.5` and `^11.2.4`.** Shipped in the tarball's manifest only; `dist/` is
+  unchanged by them.
+
 ## [1.6.0] - 2026-08-29
 
 A readiness check that fails without rejecting left no record an operator would
@@ -1003,4 +1086,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.5.2]: https://github.com/bymaxone/nest-core/compare/v1.5.1...v1.5.2
 [1.5.3]: https://github.com/bymaxone/nest-core/compare/v1.5.2...v1.5.3
 [1.6.0]: https://github.com/bymaxone/nest-core/compare/v1.5.3...v1.6.0
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.0...HEAD
+[1.6.1]: https://github.com/bymaxone/nest-core/compare/v1.6.0...v1.6.1
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.1...HEAD

package/README.md

@@ -1163,10 +1163,35 @@ can emit it once and never branch:
 
 | Result                                     | Meaning                                                 |
 | ------------------------------------------ | ------------------------------------------------------- |
-| `{ mounted: true, path }`                  | The UI and the document are served at `path`.           |
+| `{ mounted: true, path, discarded }`       | The UI and the document are served at `path`.           |
 | `{ mounted: false, reason: 'disabled' }`   | `openapi.enabled` is off.                               |
 | `{ mounted: false, reason: 'production' }` | The runtime is production. Nothing was built or served. |
 
+`discarded` lists every component entry a library contributed that the served
+document already defined with a shape of its own — a `DiscardedComponent` per
+entry, naming the contributor, the member and the name. It is empty when every
+contribution was placed, and the boot log reports the same entries.
+
+A collision is not an error and does not stop the boot: the merge prefers
+whatever holds the name already. That is usually your own declaration, and you
+authored it on purpose — but it may also be a core schema this package
+contributes under `openapi.includeCoreSchemas`, or an earlier contributor's
+entry, since contributors merge in class-name order. The report names what was
+dropped and by whom, not who owns the definition that won, so read the document
+before deciding what to remove.
+
+It is reported because it is otherwise unobservable from either side: the
+contributing library cannot tell its entry lost, the application cannot tell one
+was offered, and the served document looks the same either way.
+
+A schema present only as `{"type":"object","properties":{}}` is **not** a
+declaration for this purpose. `@nestjs/swagger` emits exactly that for every DTO
+in a package built without its plugin, so such a name is filled from the
+contribution rather than preferred over it, and does not appear in `discarded`.
+An empty `required: []` and a `description` do not change that; anything else
+does. `{"type":"object"}` and `{}` are deliberate declarations — "any object" and
+"any value" — and are kept.
+
 ### Production is a closed door
 
 `NODE_ENV` decides, and the decision is fail-closed: only `development` and
@@ -1773,6 +1798,7 @@ in the sections above.
 | -------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------ |
 | `applyBymaxOpenApi`                                                                    | function            | Builds and mounts the document; call it before `app.listen()`.                 |
 | `OpenApiMountOutcome`                                                                  | type                | What the helper did: mounted at a path, or skipped with a reason.              |
+| `DiscardedComponent`                                                                   | type                | A contributed component entry the document already declared.                   |
 | `OpenApiSkipReason`                                                                    | type                | Why it was skipped: `'disabled'` or `'production'`.                            |
 | `BymaxOpenApiContributor`, `BYMAX_OPENAPI_CONTRIBUTOR_METADATA`                        | decorator, constant | Marks a provider as describing its own routes, and the metadata key behind it. |
 | `IOpenApiContributor`, `OpenApiFragment`, `OpenApiFragmentObject`, `OpenApiHandlerKey` | types               | The contributor contract and the shape of what it returns.                     |

package/dist/openapi/index.cjs

@@ -134,6 +134,82 @@ function collectContributions(discovery, reflector, handlers) {
   });
 }
 
+// src/openapi/openapi.shape.ts
+var OPERATION_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+  "trace"
+];
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+function operationsOf(item) {
+  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
+}
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+// src/openapi/openapi.components.ts
+function isEmptyRequired(key, value) {
+  return key === "required" && Array.isArray(value) && value.length === 0;
+}
+var IGNORABLE_KEYS = /* @__PURE__ */ new Set(["type", "properties", "description"]);
+function describesNoShape(entry) {
+  const type = entry["type"];
+  if (type !== void 0 && type !== "object") {
+    return false;
+  }
+  const properties = entry["properties"];
+  if (!Object.hasOwn(entry, "properties") || asRecord(properties) !== properties) {
+    return false;
+  }
+  if (Object.keys(asRecord(properties)).length > 0) {
+    return false;
+  }
+  return Object.entries(entry).every(
+    ([key, value]) => IGNORABLE_KEYS.has(key) || isEmptyRequired(key, value)
+  );
+}
+function placeComponentEntries(existing, member, offered, onKept) {
+  const next = new Map(Object.entries(asRecord(existing)));
+  for (const [name, contributed] of Object.entries(asRecord(offered))) {
+    const declared = next.get(name);
+    const held = asRecord(declared);
+    const replaceable = member === "schemas" && describesNoShape(held);
+    if (declared !== void 0 && !replaceable) {
+      onKept(name);
+      continue;
+    }
+    const described = held["description"];
+    next.set(
+      name,
+      described === void 0 || described === "" ? contributed : { ...asRecord(contributed), description: described }
+    );
+  }
+  return Object.fromEntries(next);
+}
+function mergeContributedComponents(merged, contributions) {
+  const discarded = [];
+  for (const contribution of contributions) {
+    for (const [member, entries] of Object.entries(contribution.components)) {
+      const placed = placeComponentEntries(merged.get(member), member, entries, (name) => {
+        discarded.push({ contributor: contribution.label, member, name });
+      });
+      merged.set(member, placed);
+    }
+  }
+  return discarded;
+}
+
 // src/route-defaults.ts
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_METRICS_PATH = "metrics";
@@ -326,30 +402,6 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.shape.ts
-var OPERATION_METHODS = [
-  "get",
-  "post",
-  "put",
-  "patch",
-  "delete",
-  "head",
-  "options",
-  "trace"
-];
-function asRecord(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return {};
-  }
-  return value;
-}
-function operationsOf(item) {
-  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
-}
-function operationKey(method, path) {
-  return `${method.toUpperCase()} ${path}`;
-}
-
 // src/openapi/openapi.document.ts
 var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
 var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
@@ -541,8 +593,15 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const components = asRecord(document.components);
   const merged = new Map(Object.entries(components));
   if (openapi.includeCoreSchemas) {
-    merged.set("schemas", mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS));
-    merged.set("parameters", mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS));
+    const keep = () => void 0;
+    merged.set(
+      "schemas",
+      placeComponentEntries(components["schemas"], "schemas", CORE_SCHEMAS, keep)
+    );
+    merged.set(
+      "parameters",
+      placeComponentEntries(components["parameters"], "parameters", CORE_PARAMETERS, keep)
+    );
   }
   const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
     [METRICS_SCHEME_NAME]: {
@@ -559,11 +618,7 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   if (Object.keys(declaredSchemes).length > 0) {
     merged.set("securitySchemes", declaredSchemes);
   }
-  for (const contribution of contributions) {
-    for (const [member, entries] of Object.entries(contribution.components)) {
-      merged.set(member, mergeAbsent(asRecord(merged.get(member)), entries));
-    }
-  }
+  const discarded = mergeContributedComponents(merged, contributions);
   assertSchemesDeclared(openapi, asRecord(merged.get("securitySchemes")));
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
@@ -578,7 +633,10 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
     )
   };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
-  return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
+  return {
+    document: { ...document, components: Object.fromEntries(merged), ...paths, ...security },
+    discarded
+  };
 }
 
 // src/optional-peer.ts
@@ -673,6 +731,16 @@ function warnUnsecuredOperations(logger, keys) {
     `a client generated from the OpenAPI document will send no credentials to ${keys.length} operation(s): ${listed}${elided > 0 ? `, and ${elided} more` : ""}. They state no security requirement, the document declares no default, and other operations in it do state one \u2014 so this is more often a missing openapi.security default than a public API. Set openapi.security, or state the intent per operation with an explicit [] in openapi.operationSecurity.`
   );
 }
+function warnDiscardedComponents(logger, discarded) {
+  if (discarded.length === 0) {
+    return;
+  }
+  const elided = discarded.length - MAX_WARNED_OPERATIONS;
+  const listed = discarded.slice(0, MAX_WARNED_OPERATIONS).map(({ contributor, member, name }) => `${contributor} -> ${member}.${name}`).join(", ");
+  logger.warn(
+    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
+  );
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -702,13 +770,19 @@ async function applyBymaxOpenApi(app) {
     operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
   });
   const prefixes = readPathPrefixes(app);
-  const document = augmentDocument(generated, resolved, prefixes, readContributions(app, handlers));
+  const { document, discarded } = augmentDocument(
+    generated,
+    resolved,
+    prefixes,
+    readContributions(app, handlers)
+  );
   warnUnsecuredOperations(logger, unsecuredOperations(document, resolved, prefixes));
+  warnDiscardedComponents(logger, discarded);
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
   });
   logger.log(`OpenAPI document served at "/${options.path}" (JSON at "/${options.jsonPath}")`);
-  return { mounted: true, path: options.path };
+  return { mounted: true, path: options.path, discarded };
 }
 
 exports.BYMAX_OPENAPI_CONTRACT_VERSION = BYMAX_OPENAPI_CONTRACT_VERSION;

package/dist/openapi/index.d.cts

@@ -1,55 +1,4 @@
-import { INestApplication, CustomDecorator } from '@nestjs/common';
-
-/** Why the document was not mounted. */
-type OpenApiSkipReason = 
-/** The consumer never enabled the feature. */
-'disabled'
-/** The runtime is production, where the document is never served. */
- | 'production';
-/** What {@link applyBymaxOpenApi} did, so a caller can assert on it. */
-interface OpenApiMountOutcome {
-    /** Whether the document and its UI were mounted. */
-    mounted: boolean;
-    /** Present only when `mounted` is `false`. */
-    reason?: OpenApiSkipReason;
-    /** The route the UI was mounted at. Present only when `mounted` is `true`. */
-    path?: string;
-}
-/**
- * Build and mount the OpenAPI document and its interactive UI, when the
- * configuration and the runtime both allow it.
- *
- * Call it once, after `NestFactory.create` and BEFORE the application starts
- * listening. The ordering is not a style preference: mounting the document
- * re-registers routes on the HTTP adapter, and on Express 5 doing that against
- * an already-initialized application replaces the router — every route the
- * application had, including its own controllers and this package's health
- * endpoints, stops resolving. `app.listen()` performs that initialization, so
- * "before listening" is the whole rule.
- *
- * It is safe to call unconditionally: with the feature disabled, or in
- * production, it mounts nothing, loads no optional peer, and returns why.
- *
- * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
- * dynamic `import()`, which is what keeps the peer optional for everyone who
- * never enables the document — and Jest's module registry cannot service a
- * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
- * only the *enabled* path fails, with `dynamic import callback invoked without
- * --experimental-vm-modules`; the disabled and production paths never reach the
- * loader and pass either way, which is what makes the omission confusing.
- *
- * @param app - The created Nest application, not yet listening.
- * @returns What happened: mounted, or skipped with a reason.
- * @throws Error When `BymaxCoreModule` is not registered, when the feature is
- *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
- *   `openapi.operationSecurity` addresses an operation the generated document
- *   does not contain.
- * @example
- *   const app = await NestFactory.create(AppModule)
- *   await applyBymaxOpenApi(app)
- *   await app.listen(3000)
- */
-declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+import { CustomDecorator, INestApplication } from '@nestjs/common';
 
 /**
  * Addresses one route handler, as `'<ControllerClassName>.<methodName>'`.
@@ -196,4 +145,99 @@ declare const BYMAX_OPENAPI_CONTRIBUTOR_METADATA = "bymax-one:openapi-contributo
  */
 declare function BymaxOpenApiContributor(): CustomDecorator<string>;
 
-export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };
+/**
+ * @fileoverview Placing offered entries — this package's catalogue and every
+ * library contribution — into a document's `components`, and reporting what a
+ * contributor could not place.
+ *
+ * A module of its own because the rule here is not the document's rule: everywhere else the merge is "the existing side wins", and this is the
+ * one place that asks whether the existing side says anything at all. Keeping
+ * the question and its narrow carve-out together makes the exception legible as
+ * an exception.
+ * @layer internal
+ */
+
+/**
+ * One component entry a contributor offered and the document already declared.
+ *
+ * Carries the contributor's label because a collision is only actionable if you
+ * know who lost it: an application with several contributing libraries would
+ * otherwise be told a name was dropped without being told whose it was.
+ */
+interface DiscardedComponent {
+    /** The contributing class, as {@link ResolvedContribution.label} names it. */
+    readonly contributor: string;
+    /** The component member, such as `schemas` or `parameters`. */
+    readonly member: string;
+    /** The entry's name within that member. */
+    readonly name: string;
+}
+
+/** Why the document was not mounted. */
+type OpenApiSkipReason = 
+/** The consumer never enabled the feature. */
+'disabled'
+/** The runtime is production, where the document is never served. */
+ | 'production';
+/** What {@link applyBymaxOpenApi} did, so a caller can assert on it. */
+interface OpenApiMountOutcome {
+    /** Whether the document and its UI were mounted. */
+    mounted: boolean;
+    /** Present only when `mounted` is `false`. */
+    reason?: OpenApiSkipReason;
+    /** The route the UI was mounted at. Present only when `mounted` is `true`. */
+    path?: string;
+    /**
+     * Component entries a contributor offered that the served document already
+     * defined with a shape of its own. Present only when `mounted` is `true`;
+     * empty when every contribution was placed.
+     *
+     * The merge prefers whatever holds the name already, so a collision is not an
+     * error and does not stop the boot. The holder is usually the application's
+     * own declaration, but it may be a core schema this package contributes under
+     * `openapi.includeCoreSchemas` or an earlier contributor's entry — the report
+     * names what was dropped and by whom, not who owns the winning definition.
+     *
+     * It is reported because it is otherwise unobservable from either side: the
+     * contributing library cannot tell its entry was dropped, and the application
+     * cannot tell one was offered.
+     */
+    discarded?: readonly DiscardedComponent[];
+}
+/**
+ * Build and mount the OpenAPI document and its interactive UI, when the
+ * configuration and the runtime both allow it.
+ *
+ * Call it once, after `NestFactory.create` and BEFORE the application starts
+ * listening. The ordering is not a style preference: mounting the document
+ * re-registers routes on the HTTP adapter, and on Express 5 doing that against
+ * an already-initialized application replaces the router — every route the
+ * application had, including its own controllers and this package's health
+ * endpoints, stops resolving. `app.listen()` performs that initialization, so
+ * "before listening" is the whole rule.
+ *
+ * It is safe to call unconditionally: with the feature disabled, or in
+ * production, it mounts nothing, loads no optional peer, and returns why.
+ *
+ * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
+ * dynamic `import()`, which is what keeps the peer optional for everyone who
+ * never enables the document — and Jest's module registry cannot service a
+ * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
+ * only the *enabled* path fails, with `dynamic import callback invoked without
+ * --experimental-vm-modules`; the disabled and production paths never reach the
+ * loader and pass either way, which is what makes the omission confusing.
+ *
+ * @param app - The created Nest application, not yet listening.
+ * @returns What happened: mounted, or skipped with a reason.
+ * @throws Error When `BymaxCoreModule` is not registered, when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
+ *   `openapi.operationSecurity` addresses an operation the generated document
+ *   does not contain.
+ * @example
+ *   const app = await NestFactory.create(AppModule)
+ *   await applyBymaxOpenApi(app)
+ *   await app.listen(3000)
+ */
+declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+
+export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type DiscardedComponent, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };

package/dist/openapi/index.d.ts

@@ -1,55 +1,4 @@
-import { INestApplication, CustomDecorator } from '@nestjs/common';
-
-/** Why the document was not mounted. */
-type OpenApiSkipReason = 
-/** The consumer never enabled the feature. */
-'disabled'
-/** The runtime is production, where the document is never served. */
- | 'production';
-/** What {@link applyBymaxOpenApi} did, so a caller can assert on it. */
-interface OpenApiMountOutcome {
-    /** Whether the document and its UI were mounted. */
-    mounted: boolean;
-    /** Present only when `mounted` is `false`. */
-    reason?: OpenApiSkipReason;
-    /** The route the UI was mounted at. Present only when `mounted` is `true`. */
-    path?: string;
-}
-/**
- * Build and mount the OpenAPI document and its interactive UI, when the
- * configuration and the runtime both allow it.
- *
- * Call it once, after `NestFactory.create` and BEFORE the application starts
- * listening. The ordering is not a style preference: mounting the document
- * re-registers routes on the HTTP adapter, and on Express 5 doing that against
- * an already-initialized application replaces the router — every route the
- * application had, including its own controllers and this package's health
- * endpoints, stops resolving. `app.listen()` performs that initialization, so
- * "before listening" is the whole rule.
- *
- * It is safe to call unconditionally: with the feature disabled, or in
- * production, it mounts nothing, loads no optional peer, and returns why.
- *
- * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
- * dynamic `import()`, which is what keeps the peer optional for everyone who
- * never enables the document — and Jest's module registry cannot service a
- * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
- * only the *enabled* path fails, with `dynamic import callback invoked without
- * --experimental-vm-modules`; the disabled and production paths never reach the
- * loader and pass either way, which is what makes the omission confusing.
- *
- * @param app - The created Nest application, not yet listening.
- * @returns What happened: mounted, or skipped with a reason.
- * @throws Error When `BymaxCoreModule` is not registered, when the feature is
- *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
- *   `openapi.operationSecurity` addresses an operation the generated document
- *   does not contain.
- * @example
- *   const app = await NestFactory.create(AppModule)
- *   await applyBymaxOpenApi(app)
- *   await app.listen(3000)
- */
-declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+import { CustomDecorator, INestApplication } from '@nestjs/common';
 
 /**
  * Addresses one route handler, as `'<ControllerClassName>.<methodName>'`.
@@ -196,4 +145,99 @@ declare const BYMAX_OPENAPI_CONTRIBUTOR_METADATA = "bymax-one:openapi-contributo
  */
 declare function BymaxOpenApiContributor(): CustomDecorator<string>;
 
-export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };
+/**
+ * @fileoverview Placing offered entries — this package's catalogue and every
+ * library contribution — into a document's `components`, and reporting what a
+ * contributor could not place.
+ *
+ * A module of its own because the rule here is not the document's rule: everywhere else the merge is "the existing side wins", and this is the
+ * one place that asks whether the existing side says anything at all. Keeping
+ * the question and its narrow carve-out together makes the exception legible as
+ * an exception.
+ * @layer internal
+ */
+
+/**
+ * One component entry a contributor offered and the document already declared.
+ *
+ * Carries the contributor's label because a collision is only actionable if you
+ * know who lost it: an application with several contributing libraries would
+ * otherwise be told a name was dropped without being told whose it was.
+ */
+interface DiscardedComponent {
+    /** The contributing class, as {@link ResolvedContribution.label} names it. */
+    readonly contributor: string;
+    /** The component member, such as `schemas` or `parameters`. */
+    readonly member: string;
+    /** The entry's name within that member. */
+    readonly name: string;
+}
+
+/** Why the document was not mounted. */
+type OpenApiSkipReason = 
+/** The consumer never enabled the feature. */
+'disabled'
+/** The runtime is production, where the document is never served. */
+ | 'production';
+/** What {@link applyBymaxOpenApi} did, so a caller can assert on it. */
+interface OpenApiMountOutcome {
+    /** Whether the document and its UI were mounted. */
+    mounted: boolean;
+    /** Present only when `mounted` is `false`. */
+    reason?: OpenApiSkipReason;
+    /** The route the UI was mounted at. Present only when `mounted` is `true`. */
+    path?: string;
+    /**
+     * Component entries a contributor offered that the served document already
+     * defined with a shape of its own. Present only when `mounted` is `true`;
+     * empty when every contribution was placed.
+     *
+     * The merge prefers whatever holds the name already, so a collision is not an
+     * error and does not stop the boot. The holder is usually the application's
+     * own declaration, but it may be a core schema this package contributes under
+     * `openapi.includeCoreSchemas` or an earlier contributor's entry — the report
+     * names what was dropped and by whom, not who owns the winning definition.
+     *
+     * It is reported because it is otherwise unobservable from either side: the
+     * contributing library cannot tell its entry was dropped, and the application
+     * cannot tell one was offered.
+     */
+    discarded?: readonly DiscardedComponent[];
+}
+/**
+ * Build and mount the OpenAPI document and its interactive UI, when the
+ * configuration and the runtime both allow it.
+ *
+ * Call it once, after `NestFactory.create` and BEFORE the application starts
+ * listening. The ordering is not a style preference: mounting the document
+ * re-registers routes on the HTTP adapter, and on Express 5 doing that against
+ * an already-initialized application replaces the router — every route the
+ * application had, including its own controllers and this package's health
+ * endpoints, stops resolving. `app.listen()` performs that initialization, so
+ * "before listening" is the whole rule.
+ *
+ * It is safe to call unconditionally: with the feature disabled, or in
+ * production, it mounts nothing, loads no optional peer, and returns why.
+ *
+ * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
+ * dynamic `import()`, which is what keeps the peer optional for everyone who
+ * never enables the document — and Jest's module registry cannot service a
+ * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
+ * only the *enabled* path fails, with `dynamic import callback invoked without
+ * --experimental-vm-modules`; the disabled and production paths never reach the
+ * loader and pass either way, which is what makes the omission confusing.
+ *
+ * @param app - The created Nest application, not yet listening.
+ * @returns What happened: mounted, or skipped with a reason.
+ * @throws Error When `BymaxCoreModule` is not registered, when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
+ *   `openapi.operationSecurity` addresses an operation the generated document
+ *   does not contain.
+ * @example
+ *   const app = await NestFactory.create(AppModule)
+ *   await applyBymaxOpenApi(app)
+ *   await app.listen(3000)
+ */
+declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+
+export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type DiscardedComponent, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };

package/dist/openapi/index.mjs

@@ -132,6 +132,82 @@ function collectContributions(discovery, reflector, handlers) {
   });
 }
 
+// src/openapi/openapi.shape.ts
+var OPERATION_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+  "trace"
+];
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+function operationsOf(item) {
+  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
+}
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+// src/openapi/openapi.components.ts
+function isEmptyRequired(key, value) {
+  return key === "required" && Array.isArray(value) && value.length === 0;
+}
+var IGNORABLE_KEYS = /* @__PURE__ */ new Set(["type", "properties", "description"]);
+function describesNoShape(entry) {
+  const type = entry["type"];
+  if (type !== void 0 && type !== "object") {
+    return false;
+  }
+  const properties = entry["properties"];
+  if (!Object.hasOwn(entry, "properties") || asRecord(properties) !== properties) {
+    return false;
+  }
+  if (Object.keys(asRecord(properties)).length > 0) {
+    return false;
+  }
+  return Object.entries(entry).every(
+    ([key, value]) => IGNORABLE_KEYS.has(key) || isEmptyRequired(key, value)
+  );
+}
+function placeComponentEntries(existing, member, offered, onKept) {
+  const next = new Map(Object.entries(asRecord(existing)));
+  for (const [name, contributed] of Object.entries(asRecord(offered))) {
+    const declared = next.get(name);
+    const held = asRecord(declared);
+    const replaceable = member === "schemas" && describesNoShape(held);
+    if (declared !== void 0 && !replaceable) {
+      onKept(name);
+      continue;
+    }
+    const described = held["description"];
+    next.set(
+      name,
+      described === void 0 || described === "" ? contributed : { ...asRecord(contributed), description: described }
+    );
+  }
+  return Object.fromEntries(next);
+}
+function mergeContributedComponents(merged, contributions) {
+  const discarded = [];
+  for (const contribution of contributions) {
+    for (const [member, entries] of Object.entries(contribution.components)) {
+      const placed = placeComponentEntries(merged.get(member), member, entries, (name) => {
+        discarded.push({ contributor: contribution.label, member, name });
+      });
+      merged.set(member, placed);
+    }
+  }
+  return discarded;
+}
+
 // src/route-defaults.ts
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_METRICS_PATH = "metrics";
@@ -324,30 +400,6 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.shape.ts
-var OPERATION_METHODS = [
-  "get",
-  "post",
-  "put",
-  "patch",
-  "delete",
-  "head",
-  "options",
-  "trace"
-];
-function asRecord(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return {};
-  }
-  return value;
-}
-function operationsOf(item) {
-  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
-}
-function operationKey(method, path) {
-  return `${method.toUpperCase()} ${path}`;
-}
-
 // src/openapi/openapi.document.ts
 var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
 var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
@@ -539,8 +591,15 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const components = asRecord(document.components);
   const merged = new Map(Object.entries(components));
   if (openapi.includeCoreSchemas) {
-    merged.set("schemas", mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS));
-    merged.set("parameters", mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS));
+    const keep = () => void 0;
+    merged.set(
+      "schemas",
+      placeComponentEntries(components["schemas"], "schemas", CORE_SCHEMAS, keep)
+    );
+    merged.set(
+      "parameters",
+      placeComponentEntries(components["parameters"], "parameters", CORE_PARAMETERS, keep)
+    );
   }
   const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
     [METRICS_SCHEME_NAME]: {
@@ -557,11 +616,7 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   if (Object.keys(declaredSchemes).length > 0) {
     merged.set("securitySchemes", declaredSchemes);
   }
-  for (const contribution of contributions) {
-    for (const [member, entries] of Object.entries(contribution.components)) {
-      merged.set(member, mergeAbsent(asRecord(merged.get(member)), entries));
-    }
-  }
+  const discarded = mergeContributedComponents(merged, contributions);
   assertSchemesDeclared(openapi, asRecord(merged.get("securitySchemes")));
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
@@ -576,7 +631,10 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
     )
   };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
-  return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
+  return {
+    document: { ...document, components: Object.fromEntries(merged), ...paths, ...security },
+    discarded
+  };
 }
 
 // src/optional-peer.ts
@@ -671,6 +729,16 @@ function warnUnsecuredOperations(logger, keys) {
     `a client generated from the OpenAPI document will send no credentials to ${keys.length} operation(s): ${listed}${elided > 0 ? `, and ${elided} more` : ""}. They state no security requirement, the document declares no default, and other operations in it do state one \u2014 so this is more often a missing openapi.security default than a public API. Set openapi.security, or state the intent per operation with an explicit [] in openapi.operationSecurity.`
   );
 }
+function warnDiscardedComponents(logger, discarded) {
+  if (discarded.length === 0) {
+    return;
+  }
+  const elided = discarded.length - MAX_WARNED_OPERATIONS;
+  const listed = discarded.slice(0, MAX_WARNED_OPERATIONS).map(({ contributor, member, name }) => `${contributor} -> ${member}.${name}`).join(", ");
+  logger.warn(
+    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
+  );
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -700,13 +768,19 @@ async function applyBymaxOpenApi(app) {
     operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
   });
   const prefixes = readPathPrefixes(app);
-  const document = augmentDocument(generated, resolved, prefixes, readContributions(app, handlers));
+  const { document, discarded } = augmentDocument(
+    generated,
+    resolved,
+    prefixes,
+    readContributions(app, handlers)
+  );
   warnUnsecuredOperations(logger, unsecuredOperations(document, resolved, prefixes));
+  warnDiscardedComponents(logger, discarded);
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
   });
   logger.log(`OpenAPI document served at "/${options.path}" (JSON at "/${options.jsonPath}")`);
-  return { mounted: true, path: options.path };
+  return { mounted: true, path: options.path, discarded };
 }
 
 export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, applyBymaxOpenApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -136,7 +136,7 @@
     "@nestjs/common": "^11.1.20",
     "@nestjs/core": "^11.1.20",
     "@nestjs/platform-express": "^11.1.20",
-    "@nestjs/platform-fastify": "^11.1.29",
+    "@nestjs/platform-fastify": "^11.2.4",
     "@nestjs/swagger": "^11.4.6",
     "@nestjs/testing": "^11.1.20",
     "@opentelemetry/api": "^1.9.1",
@@ -156,7 +156,7 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-security": "^4.0.0",
-    "fastify": "^5.11.3",
+    "fastify": "^5.12.5",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "jest": "^30.4.2",