@objectstack/core 17.0.0-rc.3 → 17.0.0-rc.5

package/dist/index.js

@@ -280,7 +280,21 @@ var ObjectKernelBase = class {
     }
   }
   /**
-   * Trigger a hook with all registered handlers
+   * Trigger a hook with all registered handlers, ISOLATING failures: a
+   * handler that throws is logged and the remaining handlers still run.
+   *
+   * Use this for hooks where one subscriber's failure must not deny the
+   * others their turn — notification-style hooks, and `kernel:shutdown`,
+   * where the handlers still queued behind the failing one are the cleanup
+   * that flushes buffers and releases resources (#5257).
+   *
+   * It is the WRONG dispatcher for anything on the BOOT path. Every hook
+   * dispatched before "✅ Bootstrap complete" is a precondition of that
+   * claim, so swallowing a throw there does not rescue the boot — it only
+   * hides the failure behind a process that reports success. Those hooks
+   * (`kernel:ready`, `kernel:bootstrapped`, `kernel:listening`) use
+   * {@link triggerHookOrThrow} (#5170, #5257).
+   *
    * @param name - Hook name
    * @param args - Arguments to pass to handlers
    */
@@ -298,6 +312,54 @@ var ObjectKernelBase = class {
       }
     }
   }
+  /**
+   * Trigger a hook with all registered handlers, PROPAGATING the first
+   * failure: the remaining handlers do not run and the original error
+   * reaches the caller unwrapped.
+   *
+   * This is the dispatch semantics `ObjectKernel` has always had for every
+   * lifecycle hook (its `context.trigger` is a bare awaited loop that never
+   * catches). `LiteKernel` used the isolating {@link triggerHook} for all of
+   * them, so one hook name meant two opposite things depending on which
+   * kernel booted the same plugin code (#5170).
+   *
+   * `LiteKernel` now uses this dispatcher for all three BOOT-path hooks:
+   *
+   * - `kernel:ready` (#5170) — the only correct moment for a plugin to
+   *   assert that the preconditions it declared were actually met (the
+   *   registries are still filling during `init()`), so "declared but not
+   *   deliverable ⇒ refuse to boot" gates live there. On LiteKernel, which
+   *   is what vitest/serverless/edge run, they were downgraded to an error
+   *   log while the process carried on serving traffic without the
+   *   guarantee it claimed.
+   * - `kernel:bootstrapped` and `kernel:listening` (#5257) — the same
+   *   argument one hook later. `kernel:listening` is where HTTP server
+   *   plugins open their socket, so a swallowed failure there produced the
+   *   worst shape available: a live process printing "✅ Bootstrap complete"
+   *   with nothing listening. `kernel:bootstrapped` carries reconcile and
+   *   audit passes whose silent failure is a quieter version of the same
+   *   lie.
+   *
+   * Deliberately NOT applied to `kernel:shutdown`, which keeps
+   * {@link triggerHook}: on the teardown path a failing handler must not
+   * block the cleanup queued behind it. That is a per-hook judgement
+   * recorded at the dispatch site in `lite-kernel.ts`, not an inherited
+   * default — and it is the reason this dispatcher is chosen per hook rather
+   * than swapped in wholesale.
+   *
+   * @param name - Hook name
+   * @param args - Arguments to pass to handlers
+   */
+  async triggerHookOrThrow(name, ...args) {
+    const handlers = this.hooks.get(name) || [];
+    this.logger.debug(`Triggering hook: ${name}`, {
+      hook: name,
+      handlerCount: handlers.length
+    });
+    for (const handler of handlers) {
+      await handler(...args);
+    }
+  }
   /**
    * Get current kernel state
    */
@@ -330,6 +392,73 @@ var LEVEL_COLORS = {
   silent: ""
 };
 var RESET = "\x1B[0m";
+function tokenizeFieldName(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/([a-zA-Z])([0-9])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean).map((word) => word.toLowerCase());
+}
+function singularizeWord(word) {
+  if (/(?:ss|us|is)$/.test(word)) return word;
+  if (/(?:ch|sh|s|x|z)es$/.test(word)) return word.slice(0, -2);
+  if (/[a-z0-9]s$/.test(word)) return word.slice(0, -1);
+  return word;
+}
+var CONCATENATED_SECRET_QUALIFIERS = /* @__PURE__ */ new Set([
+  "access",
+  "account",
+  "admin",
+  "api",
+  "app",
+  "auth",
+  "bearer",
+  "client",
+  "csrf",
+  "db",
+  "database",
+  "encryption",
+  "id",
+  "jwt",
+  "master",
+  "oauth",
+  "private",
+  "public",
+  "refresh",
+  "root",
+  "secret",
+  "service",
+  "session",
+  "shared",
+  "sign",
+  "signing",
+  "ssh",
+  "token",
+  "user",
+  "webhook",
+  "xsrf"
+]);
+function isQualifiedConcatenation(word, redactWord) {
+  for (const base of [word, singularizeWord(word)]) {
+    if (base.length <= redactWord.length || !base.endsWith(redactWord)) continue;
+    if (CONCATENATED_SECRET_QUALIFIERS.has(base.slice(0, base.length - redactWord.length))) return true;
+  }
+  return false;
+}
+function containsWordRun(words, run) {
+  for (let i = 0; i + run.length <= words.length; i++) {
+    if (run.every((word, offset) => words[i + offset] === word)) return true;
+  }
+  return false;
+}
+function fieldWordsMatchPattern(nameWords, patternWords) {
+  if (patternWords.length === 0 || nameWords.length === 0) return false;
+  if (patternWords.length > 1) {
+    const glued = patternWords.join("");
+    return containsWordRun(nameWords, patternWords) || nameWords.some((word) => word === glued || singularizeWord(word) === glued);
+  }
+  const redactWord = patternWords[0];
+  const isCompound = nameWords.filter((word) => /[a-z]/.test(word)).length > 1;
+  return nameWords.some(
+    (word) => word === redactWord || isCompound && singularizeWord(word) === redactWord || isQualifiedConcatenation(word, redactWord)
+  );
+}
 function colorEnabled(stream) {
   if (typeof process !== "undefined") {
     const noColor = process.env?.NO_COLOR;
@@ -368,6 +497,7 @@ var ObjectLogger = class _ObjectLogger {
       rotation: config.rotation ?? { maxSize: "10m", maxFiles: 5 }
     };
     this.bindings = bindings;
+    this.redactPatterns = this.config.redact.map(tokenizeFieldName).filter((words) => words.length > 0);
     if (this.config.file && typeof process !== "undefined") {
       this.openFileStream(this.config.file);
     }
@@ -413,12 +543,25 @@ var ObjectLogger = class _ObjectLogger {
   isEnabled(level) {
     return LEVEL_ORDER[level] >= LEVEL_ORDER[this.config.level];
   }
+  /**
+   * Whether a meta field name names one of the configured secrets.
+   *
+   * Until #5573 this was `lower.includes(pattern)`, which redacted every
+   * field whose name merely *contained* a redact word — `keys`, `keyword`,
+   * `tokens`, `monkey`, `secretary` — and replaced its value with
+   * `***REDACTED***`, so the reader lost the fact AND was told a secret had
+   * been withheld. Matching is now on word boundaries: `key` matches
+   * `apiKey` / `api_key`, not `keys` / `monkey` / `keyword`.
+   */
+  isRedactedFieldName(key) {
+    const nameWords = tokenizeFieldName(key);
+    return this.redactPatterns.some((pattern) => fieldWordsMatchPattern(nameWords, pattern));
+  }
   redactSensitive(obj) {
     if (!obj || typeof obj !== "object") return obj;
     const redacted = Array.isArray(obj) ? [...obj] : { ...obj };
     for (const key in redacted) {
-      const lower = key.toLowerCase();
-      if (this.config.redact.some((p) => lower.includes(p.toLowerCase()))) {
+      if (this.isRedactedFieldName(key)) {
         redacted[key] = "***REDACTED***";
       } else if (typeof redacted[key] === "object" && redacted[key] !== null) {
         redacted[key] = this.redactSensitive(redacted[key]);
@@ -481,18 +624,44 @@ var ObjectLogger = class _ObjectLogger {
     this.write("warn", message, meta);
   }
   error(message, errorOrMeta, meta) {
-    if (errorOrMeta instanceof Error) {
-      this.write("error", message, meta, errorOrMeta);
-    } else {
-      this.write("error", message, errorOrMeta);
-    }
+    this.writeErrorLike("error", message, errorOrMeta, meta);
   }
   fatal(message, errorOrMeta, meta) {
+    this.writeErrorLike("fatal", message, errorOrMeta, meta);
+  }
+  /**
+   * `error`/`fatal` dispatch — the two levels whose contract has an `Error`
+   * slot in front of `meta`.
+   *
+   * The `Logger` contract declares `error(message, error?: Error, meta?)`, and
+   * `ObjectLogger` additionally tolerates a **meta object** in the `error`
+   * slot because many in-repo call sites write `logger.error(msg, { … })`.
+   * That tolerance is fine; dropping a parameter the contract *declares* is
+   * not, and that is what the previous dispatch did:
+   *
+   *     if (errorOrMeta instanceof Error) this.write(level, message, meta, errorOrMeta);
+   *     else                             this.write(level, message, errorOrMeta);
+   *
+   * With `error === undefined` the `else` branch passed `undefined` as the
+   * meta and **never read the third argument**, so every contract-shaped
+   * `logger.error(msg, undefined, { … })` call rendered a bare message with
+   * its diagnostics silently gone — ~15 such call sites across `metadata`,
+   * `metadata-protocol`, `client` and `core/security`, plus the connector
+   * reconcile seam that found this (#5575). The contract's two sibling
+   * implementations (`ConsoleLogger`/`JsonLogger` in `@objectstack/observability`)
+   * both honour the slot, so the contract was right and this class was the
+   * outlier — declared ≠ enforced, Prime Directive #10.
+   *
+   * All three shapes are now honoured. When both slots carry meta, `meta`
+   * (the later, more specific argument) wins on a key collision.
+   */
+  writeErrorLike(level, message, errorOrMeta, meta) {
     if (errorOrMeta instanceof Error) {
-      this.write("fatal", message, meta, errorOrMeta);
-    } else {
-      this.write("fatal", message, errorOrMeta);
+      this.write(level, message, meta, errorOrMeta);
+      return;
     }
+    const merged = errorOrMeta && meta ? { ...errorOrMeta, ...meta } : errorOrMeta ?? meta;
+    this.write(level, message, merged);
   }
   log(message, ...args) {
     this.info(message, args.length > 0 ? { args } : void 0);
@@ -1757,11 +1926,12 @@ var ObjectKernel = class {
     }
     this.state = "stopping";
     this.logger.info("Graceful shutdown started");
+    const shutdownTimeoutError = new Error("Shutdown timeout exceeded");
     try {
       const shutdownPromise = this.performShutdown();
       const timeoutPromise = new Promise((_, reject) => {
         const t = setTimeout(() => {
-          reject(new Error("Shutdown timeout exceeded"));
+          reject(shutdownTimeoutError);
         }, this.config.shutdownTimeout);
         if (t.unref) t.unref();
       });
@@ -1769,10 +1939,17 @@ var ObjectKernel = class {
       this.state = "stopped";
       this.logger.info("\u2705 Graceful shutdown complete");
     } catch (error) {
-      this.logger.error("Shutdown timed out \u2014 forcing exit", error);
       this.state = "stopped";
-      await this.logger.destroy();
-      process.exit(1);
+      if (error === shutdownTimeoutError) {
+        this.logger.error("Shutdown timed out \u2014 forcing exit", error);
+        await this.logger.destroy();
+        process.exit(1);
+      } else {
+        this.logger.error(
+          "Shutdown finished with an unexpected teardown error \u2014 the kernel is stopped and the process is NOT being exited; some cleanup may not have run",
+          error
+        );
+      }
     } finally {
       await this.logger.destroy();
     }
@@ -1962,8 +2139,48 @@ var ObjectKernel = class {
     }
     this.startedPlugins.clear();
   }
+  /**
+   * Dispatch `kernel:shutdown`, ISOLATING failures: a handler that throws is
+   * logged and the remaining handlers still run (#5274).
+   *
+   * This is a per-hook judgement, deliberately NOT the bare awaited loop
+   * `context.trigger` runs for every other hook — the boot-path hooks
+   * (`kernel:ready`, `kernel:bootstrapped`, `kernel:listening`) keep
+   * propagating, because everything dispatched before "✅ Bootstrap complete"
+   * is a precondition of that claim and swallowing a throw there only hides
+   * the failure behind a process reporting success (#5170, #5257).
+   *
+   * On the teardown path there is no "refuse to proceed" left to buy. What is
+   * queued behind a failing shutdown handler is the rest of the cleanup —
+   * every other subscriber, then each plugin's `destroy()` in reverse order —
+   * which is what flushes buffers, closes connections and releases locks. So
+   * one bad handler must not amplify into leaked resources and unflushed
+   * writes. Same reasoning, same wording, same `Hook handler failed:
+   * kernel:shutdown` log line as `LiteKernel`'s dispatch site, which reaches
+   * the shared isolating dispatcher `ObjectKernelBase.triggerHook` (#5257).
+   *
+   * `ObjectKernel` cannot call that dispatcher: it does not extend
+   * `ObjectKernelBase` (only `LiteKernel` does) and owns its own `hooks` map,
+   * so the semantics are mirrored here rather than shared. One hook name
+   * meaning two opposite things across the two kernels is exactly the bug
+   * #5170/#5257 closed, so the pin for this one lives on both sides too.
+   */
+  async triggerShutdownHookIsolating() {
+    const handlers = this.hooks.get("kernel:shutdown") || [];
+    this.logger.debug("Triggering hook: kernel:shutdown", {
+      hook: "kernel:shutdown",
+      handlerCount: handlers.length
+    });
+    for (const handler of handlers) {
+      try {
+        await handler();
+      } catch (error) {
+        this.logger.error("Hook handler failed: kernel:shutdown", error);
+      }
+    }
+  }
   async performShutdown() {
-    await this.context.trigger("kernel:shutdown");
+    await this.triggerShutdownHookIsolating();
     const orderedPlugins = Array.from(this.plugins.values()).reverse();
     for (const plugin of orderedPlugins) {
       if (plugin.destroy) {
@@ -2065,9 +2282,14 @@ var LiteKernel = class extends ObjectKernelBase {
     for (const plugin of orderedPlugins) {
       await this.runPluginStart(plugin);
     }
-    await this.triggerHook("kernel:ready");
-    await this.triggerHook("kernel:bootstrapped");
-    await this.triggerHook("kernel:listening");
+    try {
+      await this.triggerHookOrThrow("kernel:ready");
+      await this.triggerHookOrThrow("kernel:bootstrapped");
+      await this.triggerHookOrThrow("kernel:listening");
+    } catch (error) {
+      this.state = "stopped";
+      throw error;
+    }
     this.logger.info("\u2705 Bootstrap complete", {
       pluginCount: this.plugins.size
     });
@@ -2115,569 +2337,6 @@ var LiteKernel = class extends ObjectKernelBase {
   }
 };
 
-// src/api-registry.ts
-import { ApiRegistryEntrySchema } from "@objectstack/spec/api";
-var ApiRegistry = class {
-  constructor(logger, conflictResolution = "error", version = "1.0.0") {
-    this.apis = /* @__PURE__ */ new Map();
-    this.endpoints = /* @__PURE__ */ new Map();
-    this.routes = /* @__PURE__ */ new Map();
-    // Performance optimization: Auxiliary indices for O(1) lookups
-    this.apisByType = /* @__PURE__ */ new Map();
-    this.apisByTag = /* @__PURE__ */ new Map();
-    this.apisByStatus = /* @__PURE__ */ new Map();
-    this.logger = logger;
-    this.conflictResolution = conflictResolution;
-    this.version = version;
-    this.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  }
-  /**
-   * Register an API with its endpoints
-   * 
-   * @param api - API registry entry
-   * @throws Error if API already registered or route conflicts detected
-   */
-  registerApi(api) {
-    if (this.apis.has(api.id)) {
-      throw new Error(`[ApiRegistry] API '${api.id}' already registered`);
-    }
-    const fullApi = ApiRegistryEntrySchema.parse(api);
-    for (const endpoint of fullApi.endpoints) {
-      this.validateEndpoint(endpoint, fullApi.id);
-    }
-    this.apis.set(fullApi.id, fullApi);
-    for (const endpoint of fullApi.endpoints) {
-      this.registerEndpoint(fullApi.id, endpoint);
-    }
-    this.updateIndices(fullApi);
-    this.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.logger.info(`API registered: ${fullApi.id}`, {
-      api: fullApi.id,
-      type: fullApi.type,
-      endpointCount: fullApi.endpoints.length
-    });
-  }
-  /**
-   * Unregister an API and all its endpoints
-   * 
-   * @param apiId - API identifier
-   */
-  unregisterApi(apiId) {
-    const api = this.apis.get(apiId);
-    if (!api) {
-      throw new Error(`[ApiRegistry] API '${apiId}' not found`);
-    }
-    for (const endpoint of api.endpoints) {
-      this.unregisterEndpoint(apiId, endpoint.id);
-    }
-    this.removeFromIndices(api);
-    this.apis.delete(apiId);
-    this.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.logger.info(`API unregistered: ${apiId}`);
-  }
-  /**
-   * Register a single endpoint
-   * 
-   * @param apiId - API identifier
-   * @param endpoint - Endpoint registration
-   * @throws Error if route conflict detected
-   */
-  registerEndpoint(apiId, endpoint) {
-    const endpointKey = `${apiId}:${endpoint.id}`;
-    if (this.endpoints.has(endpointKey)) {
-      throw new Error(`[ApiRegistry] Endpoint '${endpoint.id}' already registered for API '${apiId}'`);
-    }
-    this.endpoints.set(endpointKey, { api: apiId, endpoint });
-    if (endpoint.path) {
-      this.registerRoute(apiId, endpoint);
-    }
-  }
-  /**
-   * Unregister a single endpoint
-   * 
-   * @param apiId - API identifier
-   * @param endpointId - Endpoint identifier
-   */
-  unregisterEndpoint(apiId, endpointId) {
-    const endpointKey = `${apiId}:${endpointId}`;
-    const entry = this.endpoints.get(endpointKey);
-    if (!entry) {
-      return;
-    }
-    if (entry.endpoint.path) {
-      const routeKey = this.getRouteKey(entry.endpoint);
-      this.routes.delete(routeKey);
-    }
-    this.endpoints.delete(endpointKey);
-  }
-  /**
-   * Register a route with conflict detection
-   * 
-   * @param apiId - API identifier
-   * @param endpoint - Endpoint registration
-   * @throws Error if route conflict detected (based on strategy)
-   */
-  registerRoute(apiId, endpoint) {
-    const routeKey = this.getRouteKey(endpoint);
-    const priority = endpoint.priority ?? 100;
-    const existingRoute = this.routes.get(routeKey);
-    if (existingRoute) {
-      this.handleRouteConflict(routeKey, apiId, endpoint, existingRoute, priority);
-      return;
-    }
-    this.routes.set(routeKey, {
-      api: apiId,
-      endpointId: endpoint.id,
-      priority
-    });
-  }
-  /**
-   * Handle route conflict based on resolution strategy
-   * 
-   * @param routeKey - Route key
-   * @param apiId - New API identifier
-   * @param endpoint - New endpoint
-   * @param existingRoute - Existing route registration
-   * @param newPriority - New endpoint priority
-   * @throws Error if strategy is 'error'
-   */
-  handleRouteConflict(routeKey, apiId, endpoint, existingRoute, newPriority) {
-    const strategy = this.conflictResolution;
-    switch (strategy) {
-      case "error":
-        throw new Error(
-          `[ApiRegistry] Route conflict detected: '${routeKey}' is already registered by API '${existingRoute.api}' endpoint '${existingRoute.endpointId}'`
-        );
-      case "priority":
-        if (newPriority > existingRoute.priority) {
-          this.logger.warn(
-            `Route conflict: replacing '${routeKey}' (priority ${existingRoute.priority} -> ${newPriority})`,
-            {
-              oldApi: existingRoute.api,
-              oldEndpoint: existingRoute.endpointId,
-              newApi: apiId,
-              newEndpoint: endpoint.id
-            }
-          );
-          this.routes.set(routeKey, {
-            api: apiId,
-            endpointId: endpoint.id,
-            priority: newPriority
-          });
-        } else {
-          this.logger.warn(
-            `Route conflict: keeping existing '${routeKey}' (priority ${existingRoute.priority} >= ${newPriority})`,
-            {
-              existingApi: existingRoute.api,
-              existingEndpoint: existingRoute.endpointId,
-              newApi: apiId,
-              newEndpoint: endpoint.id
-            }
-          );
-        }
-        break;
-      case "first-wins":
-        this.logger.warn(
-          `Route conflict: keeping first registered '${routeKey}'`,
-          {
-            existingApi: existingRoute.api,
-            newApi: apiId
-          }
-        );
-        break;
-      case "last-wins":
-        this.logger.warn(
-          `Route conflict: replacing with last registered '${routeKey}'`,
-          {
-            oldApi: existingRoute.api,
-            newApi: apiId
-          }
-        );
-        this.routes.set(routeKey, {
-          api: apiId,
-          endpointId: endpoint.id,
-          priority: newPriority
-        });
-        break;
-      default:
-        throw new Error(`[ApiRegistry] Unknown conflict resolution strategy: ${strategy}`);
-    }
-  }
-  /**
-   * Generate a unique route key for conflict detection
-   * 
-   * NOTE: This implementation uses exact string matching for route conflict detection.
-   * It works well for static paths but has limitations with parameterized routes.
-   * For example, `/api/users/:id` and `/api/users/:userId` will NOT be detected as conflicts
-   * even though they are semantically identical parameterized patterns. Similarly,
-   * `/api/:resource/list` and `/api/:entity/list` would also not be detected as conflicting.
-   * 
-   * For more advanced conflict detection (e.g., path-to-regexp pattern matching),
-   * consider integrating with your routing library's conflict detection mechanism.
-   * 
-   * @param endpoint - Endpoint registration
-   * @returns Route key (e.g., "GET:/api/v1/customers/:id")
-   */
-  getRouteKey(endpoint) {
-    const method = endpoint.method || "ANY";
-    return `${method}:${endpoint.path}`;
-  }
-  /**
-   * Validate endpoint registration
-   * 
-   * @param endpoint - Endpoint to validate
-   * @param apiId - API identifier (for error messages)
-   * @throws Error if endpoint is invalid
-   */
-  validateEndpoint(endpoint, apiId) {
-    if (!endpoint.id) {
-      throw new Error(`[ApiRegistry] Endpoint in API '${apiId}' missing 'id' field`);
-    }
-    if (!endpoint.path) {
-      throw new Error(`[ApiRegistry] Endpoint '${endpoint.id}' in API '${apiId}' missing 'path' field`);
-    }
-  }
-  /**
-   * Get an API by ID
-   * 
-   * @param apiId - API identifier
-   * @returns API registry entry or undefined
-   */
-  getApi(apiId) {
-    return this.apis.get(apiId);
-  }
-  /**
-   * Get all registered APIs
-   * 
-   * @returns Array of all APIs
-   */
-  getAllApis() {
-    return Array.from(this.apis.values());
-  }
-  /**
-   * Find APIs matching query criteria
-   * 
-   * Performance optimized with auxiliary indices for O(1) lookups on type, tags, and status.
-   * 
-   * @param query - Discovery query parameters
-   * @returns Matching APIs
-   */
-  findApis(query) {
-    let resultIds;
-    if (query.type) {
-      const typeIds = this.apisByType.get(query.type);
-      if (!typeIds || typeIds.size === 0) {
-        return { apis: [], total: 0, filters: query };
-      }
-      resultIds = new Set(typeIds);
-    }
-    if (query.status) {
-      const statusIds = this.apisByStatus.get(query.status);
-      if (!statusIds || statusIds.size === 0) {
-        return { apis: [], total: 0, filters: query };
-      }
-      if (resultIds) {
-        resultIds = new Set([...resultIds].filter((id) => statusIds.has(id)));
-      } else {
-        resultIds = new Set(statusIds);
-      }
-      if (resultIds.size === 0) {
-        return { apis: [], total: 0, filters: query };
-      }
-    }
-    if (query.tags && query.tags.length > 0) {
-      const tagMatches = /* @__PURE__ */ new Set();
-      for (const tag of query.tags) {
-        const tagIds = this.apisByTag.get(tag);
-        if (tagIds) {
-          tagIds.forEach((id) => tagMatches.add(id));
-        }
-      }
-      if (tagMatches.size === 0) {
-        return { apis: [], total: 0, filters: query };
-      }
-      if (resultIds) {
-        resultIds = new Set([...resultIds].filter((id) => tagMatches.has(id)));
-      } else {
-        resultIds = tagMatches;
-      }
-      if (resultIds.size === 0) {
-        return { apis: [], total: 0, filters: query };
-      }
-    }
-    let results;
-    if (resultIds) {
-      results = Array.from(resultIds).map((id) => this.apis.get(id)).filter((api) => api !== void 0);
-    } else {
-      results = Array.from(this.apis.values());
-    }
-    if (query.pluginSource) {
-      results = results.filter(
-        (api) => api.metadata?.pluginSource === query.pluginSource
-      );
-    }
-    if (query.version) {
-      results = results.filter((api) => api.version === query.version);
-    }
-    if (query.search) {
-      const searchLower = query.search.toLowerCase();
-      results = results.filter(
-        (api) => api.name.toLowerCase().includes(searchLower) || api.description && api.description.toLowerCase().includes(searchLower)
-      );
-    }
-    return {
-      apis: results,
-      total: results.length,
-      filters: query
-    };
-  }
-  /**
-   * Get endpoint by API ID and endpoint ID
-   * 
-   * @param apiId - API identifier
-   * @param endpointId - Endpoint identifier
-   * @returns Endpoint registration or undefined
-   */
-  getEndpoint(apiId, endpointId) {
-    const key = `${apiId}:${endpointId}`;
-    return this.endpoints.get(key)?.endpoint;
-  }
-  /**
-   * Find endpoint by route (method + path)
-   * 
-   * @param method - HTTP method
-   * @param path - URL path
-   * @returns Endpoint registration or undefined
-   */
-  findEndpointByRoute(method, path) {
-    const routeKey = `${method}:${path}`;
-    const route = this.routes.get(routeKey);
-    if (!route) {
-      return void 0;
-    }
-    const api = this.apis.get(route.api);
-    const endpoint = this.getEndpoint(route.api, route.endpointId);
-    if (!api || !endpoint) {
-      return void 0;
-    }
-    return { api, endpoint };
-  }
-  /**
-   * Get complete registry snapshot
-   * 
-   * @returns Current registry state
-   */
-  getRegistry() {
-    const apis = Array.from(this.apis.values());
-    const byType = {};
-    for (const api of apis) {
-      if (!byType[api.type]) {
-        byType[api.type] = [];
-      }
-      byType[api.type].push(api);
-    }
-    const byStatus = {};
-    for (const api of apis) {
-      const status = api.metadata?.status || "active";
-      if (!byStatus[status]) {
-        byStatus[status] = [];
-      }
-      byStatus[status].push(api);
-    }
-    const totalEndpoints = apis.reduce(
-      (sum, api) => sum + api.endpoints.length,
-      0
-    );
-    return {
-      version: this.version,
-      conflictResolution: this.conflictResolution,
-      apis,
-      totalApis: apis.length,
-      totalEndpoints,
-      byType,
-      byStatus,
-      updatedAt: this.updatedAt
-    };
-  }
-  /**
-   * Clear all registered APIs
-   * 
-   * **⚠️ SAFETY WARNING:**
-   * This method clears all registered APIs and should be used with caution.
-   * 
-   * **Usage Restrictions:**
-   * - In production environments (NODE_ENV=production), a `force: true` parameter is required
-   * - Primarily intended for testing and development hot-reload scenarios
-   * 
-   * @param options - Clear options
-   * @param options.force - Force clear in production environment (default: false)
-   * @throws Error if called in production without force flag
-   * 
-   * @example Safe usage in tests
-   * ```typescript
-   * beforeEach(() => {
-   *   registry.clear(); // OK in test environment
-   * });
-   * ```
-   * 
-   * @example Usage in production (requires explicit force)
-   * ```typescript
-   * // In production, explicit force is required
-   * registry.clear({ force: true });
-   * ```
-   */
-  clear(options = {}) {
-    const isProduction = this.isProductionEnvironment();
-    if (isProduction && !options.force) {
-      throw new Error(
-        "[ApiRegistry] Cannot clear registry in production environment without force flag. Use clear({ force: true }) if you really want to clear the registry."
-      );
-    }
-    this.apis.clear();
-    this.endpoints.clear();
-    this.routes.clear();
-    this.apisByType.clear();
-    this.apisByTag.clear();
-    this.apisByStatus.clear();
-    this.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    if (isProduction) {
-      this.logger.warn("API registry forcefully cleared in production", { force: options.force });
-    } else {
-      this.logger.info("API registry cleared");
-    }
-  }
-  /**
-   * Get registry statistics
-   * 
-   * @returns Registry statistics
-   */
-  getStats() {
-    const apis = Array.from(this.apis.values());
-    const apisByType = {};
-    for (const api of apis) {
-      apisByType[api.type] = (apisByType[api.type] || 0) + 1;
-    }
-    const endpointsByApi = {};
-    for (const api of apis) {
-      endpointsByApi[api.id] = api.endpoints.length;
-    }
-    return {
-      totalApis: this.apis.size,
-      totalEndpoints: this.endpoints.size,
-      totalRoutes: this.routes.size,
-      apisByType,
-      endpointsByApi
-    };
-  }
-  /**
-   * Update auxiliary indices when an API is registered
-   * 
-   * @param api - API entry to index
-   * @private
-   * @internal
-   */
-  updateIndices(api) {
-    this.ensureIndexSet(this.apisByType, api.type).add(api.id);
-    const status = api.metadata?.status || "active";
-    this.ensureIndexSet(this.apisByStatus, status).add(api.id);
-    const tags = api.metadata?.tags || [];
-    for (const tag of tags) {
-      this.ensureIndexSet(this.apisByTag, tag).add(api.id);
-    }
-  }
-  /**
-   * Remove API from auxiliary indices when unregistered
-   * 
-   * @param api - API entry to remove from indices
-   * @private
-   * @internal
-   */
-  removeFromIndices(api) {
-    this.removeFromIndexSet(this.apisByType, api.type, api.id);
-    const status = api.metadata?.status || "active";
-    this.removeFromIndexSet(this.apisByStatus, status, api.id);
-    const tags = api.metadata?.tags || [];
-    for (const tag of tags) {
-      this.removeFromIndexSet(this.apisByTag, tag, api.id);
-    }
-  }
-  /**
-   * Helper to ensure an index set exists and return it
-   * 
-   * @param map - Index map
-   * @param key - Index key
-   * @returns The Set for this key (created if needed)
-   * @private
-   * @internal
-   */
-  ensureIndexSet(map, key) {
-    let set = map.get(key);
-    if (!set) {
-      set = /* @__PURE__ */ new Set();
-      map.set(key, set);
-    }
-    return set;
-  }
-  /**
-   * Helper to remove an ID from an index set and clean up empty sets
-   * 
-   * @param map - Index map
-   * @param key - Index key
-   * @param id - API ID to remove
-   * @private
-   * @internal
-   */
-  removeFromIndexSet(map, key, id) {
-    const set = map.get(key);
-    if (set) {
-      set.delete(id);
-      if (set.size === 0) {
-        map.delete(key);
-      }
-    }
-  }
-  /**
-   * Check if running in production environment
-   * 
-   * @returns true if NODE_ENV is 'production'
-   * @private
-   * @internal
-   */
-  isProductionEnvironment() {
-    return getEnv("NODE_ENV") === "production";
-  }
-};
-
-// src/api-registry-plugin.ts
-function createApiRegistryPlugin(config = {}) {
-  const {
-    conflictResolution = "error",
-    version = "1.0.0"
-  } = config;
-  return {
-    name: "com.objectstack.core.api-registry",
-    /**
-     * Services init() registers on every path (ADR-0116, #4131) — lets the
-     * kernel name this plugin when a consumer requires one before it inits.
-     */
-    providesServices: ["api-registry"],
-    type: "standard",
-    version: "1.0.0",
-    init: async (ctx) => {
-      const registry = new ApiRegistry(
-        ctx.logger,
-        conflictResolution,
-        version
-      );
-      ctx.registerService("api-registry", registry);
-      ctx.logger.info("API Registry plugin initialized", {
-        conflictResolution,
-        version
-      });
-    }
-  };
-}
-
 // src/qa/index.ts
 var qa_exports = {};
 __export(qa_exports, {
@@ -5656,10 +5315,11 @@ var PluginHealthMonitor = class {
     const checks = [];
     try {
       if (config.checkMethod && typeof plugin[config.checkMethod] === "function") {
-        const checkResult = await Promise.race([
+        const checkResult = await this.raceCheckTimeout(
           plugin[config.checkMethod](),
-          this.timeout(config.timeout, `Health check timeout after ${config.timeout}ms`)
-        ]);
+          config.timeout,
+          `Health check timeout after ${config.timeout}ms`
+        );
         if (checkResult === false || checkResult && checkResult.status === "unhealthy") {
           status = "unhealthy";
           message = checkResult?.message || "Custom health check failed";
@@ -5815,12 +5475,39 @@ var PluginHealthMonitor = class {
     this.logger.info("Health monitor shutdown complete");
   }
   /**
-   * Timeout helper
+   * Race a plugin's custom health check against its timeout guard, and
+   * reclaim the guard the moment the race settles (#4875).
+   *
+   * Same shape, same reasoning as `ObjectKernel.raceStartupTimeout()` (#4813,
+   * PR #4874): the guard used to be armed and then abandoned — when the check
+   * won the race, its `setTimeout` stayed ref'd in the event loop for the full
+   * `config.timeout`. Health checks are *periodic*, so unlike the kernel's
+   * one-shot startup guards the orphans here accumulate: one per plugin per
+   * round, each pinning the loop for `config.timeout`.
+   *
+   * Clearing on settle rather than `unref()`-ing at arm time is deliberate.
+   * An unref'd guard also stops pinning the loop, but it stops being a guard
+   * as well: if the check never settles and nothing else keeps the loop alive,
+   * Node exits before the timer can fire and the timeout is never reported.
+   * The guard has to stay ref'd exactly as long as the race is undecided,
+   * which is what `clearTimeout` in a `finally` expresses.
+   *
+   * `check` is widened to `T | PromiseLike<T>` because `checkMethod` is called
+   * dynamically off the plugin and may be synchronous; such a check wins the
+   * race immediately and the guard is reclaimed on the same turn.
    */
-  timeout(ms, message) {
-    return new Promise((_, reject) => {
-      setTimeout(() => reject(new Error(message)), ms);
+  async raceCheckTimeout(check, ms, message) {
+    let guard;
+    const timeoutPromise = new Promise((_, reject) => {
+      guard = setTimeout(() => {
+        reject(new Error(message));
+      }, ms);
     });
+    try {
+      return await Promise.race([check, timeoutPromise]);
+    } finally {
+      clearTimeout(guard);
+    }
   }
 };
 
@@ -6012,11 +5699,11 @@ var HotReloadManager = class {
       }
       if (plugin.destroy) {
         this.logger.debug("Destroying plugin", { plugin: pluginName });
-        const shutdownPromise = plugin.destroy();
-        const timeoutPromise = new Promise((_, reject) => {
-          setTimeout(() => reject(new Error("Shutdown timeout")), config.shutdownTimeout);
-        });
-        await Promise.race([shutdownPromise, timeoutPromise]);
+        await this.raceShutdownTimeout(
+          plugin.destroy(),
+          config.shutdownTimeout,
+          "Shutdown timeout"
+        );
         this.logger.debug("Plugin destroyed successfully", { plugin: pluginName });
       }
       this.logger.debug("Plugin module would be reloaded here", { plugin: pluginName });
@@ -6043,6 +5730,41 @@ var HotReloadManager = class {
       return false;
     }
   }
+  /**
+   * Race a plugin's `destroy()` against its shutdown-timeout guard, and
+   * reclaim the guard the moment the race settles (#4952).
+   *
+   * The guard used to be armed and then abandoned — byte-for-byte the leak
+   * #4813 fixed in the kernel's startup guards (PR #4874) and #4875 fixed in
+   * the periodic health checks (PR #4950): when `destroy()` won the race, its
+   * `setTimeout` stayed ref'd in the event loop for the full
+   * `shutdownTimeout`, so a hot reload that finished in milliseconds still
+   * pinned the loop for the whole budget — once per reload, per plugin.
+   *
+   * Clearing on settle rather than `unref()`-ing at arm time is deliberate.
+   * An unref'd guard also stops pinning the loop, but it stops being a guard
+   * as well: if `destroy()` never settles and nothing else keeps the loop
+   * alive, Node exits before the timer can fire and the timeout is never
+   * reported. The guard has to stay ref'd exactly as long as the race is
+   * undecided, which is what `clearTimeout` in a `finally` expresses.
+   *
+   * `shutdown` is widened to `T | PromiseLike<T>` because the Plugin contract
+   * permits a synchronous `destroy()` (`Promise<void> | void`); such a hook
+   * wins the race immediately and the guard is reclaimed on the same turn.
+   */
+  async raceShutdownTimeout(shutdown, timeout, message) {
+    let guard;
+    const timeoutPromise = new Promise((_, reject) => {
+      guard = setTimeout(() => {
+        reject(new Error(message));
+      }, timeout);
+    });
+    try {
+      return await Promise.race([shutdown, timeoutPromise]);
+    } finally {
+      clearTimeout(guard);
+    }
+  }
   /**
    * Schedule a reload with debouncing
    */
@@ -6501,7 +6223,6 @@ export {
   ANONYMOUS_DENY_MESSAGE,
   ANONYMOUS_DENY_STATUS,
   API_KEY_PREFIX,
-  ApiRegistry,
   CORE_FALLBACK_FACTORIES,
   DependencyResolver,
   HotReloadManager,
@@ -6537,7 +6258,6 @@ export {
   calendarPartsInTz,
   calendarPartsInTzOrUtc,
   counterSignPayload,
-  createApiRegistryPlugin,
   createLogger,
   createMemoryCache,
   createMemoryI18n,