fix(objectql)!: retire the dead ObjectQLEngine.use() plugin path (#4242)

The engine's own plugin loader — registerApp + an onEnable dispatch over
an ObjectQLHostContext — has zero callers repo-wide: kernel plugins go
through kernel.use() → init/start, and the manifest path routes through
registerApp() directly. The onEnable dispatch is the engine-level twin
of the #4212 disease (a lifecycle entry point that reads as a contract
and never runs); the app-bundle onEnable module export is a different,
real contract and is unchanged.

Removed use(), the ObjectQLHostContext type (constructed only inside
the dead method; un-exported from both barrels), and the write-only
hostContext field — the constructor keeps its signature and its logger
extraction, so new ObjectQL({ logger }) and ObjectQLPlugin's
hostContext option are unaffected.

Verified: objectql 1271 tests green (82 files) after a full turbo build
(71 packages) with the change in place; the 42 pre-existing local
failures reproduced identically on pristine main with the change
stashed and disappeared after rebuilding stale sibling dists —
unrelated to this diff.


Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh

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

Author: os-zhuang

.changeset/objectql-dead-use-retired.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/objectql": major
+---
+
+fix(objectql)!: retire the dead `ObjectQLEngine.use()` plugin path (#4212 follow-up)
+
+`ObjectQLEngine.use(manifestPart, runtimePart)` was the engine's own plugin
+loader: register a manifest, then dispatch the runtime part's `onEnable` with
+an `ObjectQLHostContext`. **Nothing calls it** — not the kernel (plugins go
+through `kernel.use()` → `init`/`start`), not the CLI, not a test, not an
+example, repo-wide. Its `onEnable` dispatch is the engine-level twin of the
+#4212 disease: a lifecycle entry point that reads as a contract and never
+runs. The *app-bundle* `onEnable` module export is a different, real contract
+(dispatched by AppPlugin at boot) and is unchanged.
+
+Removed:
+
+- `ObjectQLEngine.use()`.
+- `ObjectQLHostContext` (exported from `@objectstack/objectql` and
+  `@objectstack/objectql/core`) — constructed only inside the dead method.
+- The engine's private `hostContext` field — its only read outside the dead
+  method was the constructor's `logger` extraction, which stays; the
+  constructor signature is unchanged (`new ObjectQL({ logger })` keeps
+  working, as does `ObjectQLPlugin`'s `hostContext` option that feeds it).
+
+FROM → TO:
+
+- `engine.use(manifest)` → `engine.registerApp(manifest)` (the alive half —
+  the manifest service and ObjectQLPlugin already route through it).
+- `engine.use(_, { onEnable })` → a kernel plugin: `kernel.use({ name,
+  init(ctx) { … } })`; the engine is `ctx.getService('objectql')`, drivers
+  register via `engine.registerDriver()`.
+- `ObjectQLHostContext` → no replacement; the type described the context of
+  a hook that never fired.

packages/objectql/src/core.ts

@@ -37,7 +37,7 @@ export type { CompanionFieldMeta, CompanionObjectMeta } from './search-companion
 
 // Engine
 export { ObjectQL, ObjectRepository, ScopedContext } from './engine.js';
-export type { ObjectQLHostContext, HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js';
+export type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js';
 
 // Boot guard: thrown by `ObjectQL.init()` when a registered driver's connect()
 // fails (framework#3741). Embedders that boot the engine themselves can catch

packages/objectql/src/engine.ts

@@ -264,16 +264,6 @@ export type EngineMiddleware = (
   next: () => Promise<void>
 ) => Promise<void>;
 
-/**
- * Host Context provided to plugins (Internal ObjectQL Plugin System)
- */
-export interface ObjectQLHostContext {
-  ql: ObjectQL;
-  logger: Logger;
-  // Extensible map for host-specific globals (like HTTP Router, etc.)
-  [key: string]: any;
-}
-
 /**
  * Derive the registry key for a metadata item.
  *
@@ -393,9 +383,6 @@ export class ObjectQL implements IDataEngine {
   // `engine.registerFunction(...)`.
   private functions = new Map<string, FunctionEntry>();
 
-  // Host provided context additions (e.g. Server router)
-  private hostContext: Record<string, any> = {};
-
   // Realtime service for event publishing
   private realtimeService?: IRealtimeService;
 
@@ -424,7 +411,6 @@ export class ObjectQL implements IDataEngine {
   private _registry: SchemaRegistry = new SchemaRegistry();
 
   constructor(hostContext: Record<string, any> = {}) {
-    this.hostContext = hostContext;
     // Use provided logger or create a new one
     this.logger = hostContext.logger || createLogger({ level: 'info', format: 'pretty' });
     // Pick up production hardening switches from env so deployers can
@@ -463,42 +449,6 @@ export class ObjectQL implements IDataEngine {
     return this._registry;
   }
 
-  /**
-   * Load and Register a Plugin
-   */
-  async use(manifestPart: any, runtimePart?: any) {
-    this.logger.debug('Loading plugin', { 
-      hasManifest: !!manifestPart, 
-      hasRuntime: !!runtimePart 
-    });
-
-    // 1. Validate / Register Manifest
-    if (manifestPart) {
-      this.registerApp(manifestPart);
-    }
-
-    // 2. Execute Runtime
-    if (runtimePart) {
-       const pluginDef = (runtimePart as any).default || runtimePart;
-       if (pluginDef.onEnable) {
-          this.logger.debug('Executing plugin runtime onEnable');
-          
-          const context: ObjectQLHostContext = {
-            ql: this,
-            logger: this.logger,
-            // Expose the driver registry helper explicitly if needed
-            drivers: {
-                register: (driver: IDataDriver) => this.registerDriver(driver)
-            },
-            ...this.hostContext
-          };
-          
-          await pluginDef.onEnable(context);
-          this.logger.debug('Plugin runtime onEnable completed');
-       }
-    }
-  }
-
   /**
    * Register a hook
    * @param event The event name (e.g. 'beforeFind', 'afterInsert')

packages/objectql/src/index.ts

@@ -47,7 +47,7 @@ export type { CompanionFieldMeta, CompanionObjectMeta } from './search-companion
 
 // Export Engine
 export { ObjectQL, ObjectRepository, ScopedContext } from './engine.js';
-export type { ObjectQLHostContext, HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js';
+export type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js';
 export { SummaryRecomputeError } from './summary-errors.js';
 export type { SummaryRecomputeFailure } from './summary-errors.js';
 // Boot guard: thrown by `ObjectQL.init()` when a registered driver's connect()