polish: Final code review improvements - clarify warnings and type safety

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/runtime/src/kernel.ts

@@ -23,7 +23,7 @@ export class ObjectStackKernel {
 
     if (!hasObjectQLPlugin) {
       // Backward compatibility: Initialize ObjectQL directly if no plugin provides it
-      console.warn('[Kernel] No ObjectQL plugin detected. Using default initialization. Consider using ObjectQLPlugin for explicit registration.');
+      console.warn('[Kernel] No ObjectQL plugin found, using default initialization. Consider using ObjectQLPlugin.');
       this.ql = new ObjectQL({
         env: process.env.NODE_ENV || 'development'
       });

packages/runtime/src/objectql-plugin.ts

@@ -11,6 +11,11 @@ export const OBJECTQL_PLUGIN_MARKER = Symbol('objectql-plugin');
  * 
  * Registers the ObjectQL engine instance with the kernel.
  * This allows users to provide their own ObjectQL implementation or configuration.
+ * 
+ * Usage:
+ * - new ObjectQLPlugin() - Creates new ObjectQL with default settings
+ * - new ObjectQLPlugin(existingQL) - Uses existing ObjectQL instance
+ * - new ObjectQLPlugin(undefined, { custom: 'context' }) - Creates new ObjectQL with custom context
  */
 export class ObjectQLPlugin implements RuntimePlugin {
   name = 'com.objectstack.engine.objectql';
@@ -20,10 +25,15 @@ export class ObjectQLPlugin implements RuntimePlugin {
 
   private ql: ObjectQL;
 
+  /**
+   * @param ql - Existing ObjectQL instance to use (optional)
+   * @param hostContext - Host context for new ObjectQL instance (ignored if ql is provided)
+   */
   constructor(ql?: ObjectQL, hostContext?: Record<string, any>) {
-    // Allow passing existing ObjectQL instance or create a new one
-    // Note: If 'ql' is provided, 'hostContext' is ignored
-    // To create a new instance with custom context, pass only hostContext
+    if (ql && hostContext) {
+      console.warn('[ObjectQLPlugin] Both ql and hostContext provided. hostContext will be ignored.');
+    }
+    
     if (ql) {
       this.ql = ql;
     } else {

test-objectql-plugin.ts

@@ -42,13 +42,16 @@ async function testBackwardCompatibility() {
 async function testCustomObjectQL() {
   console.log('\n=== Test 3: Custom ObjectQL Instance ===');
 
+  // Create a WeakMap to track custom instances in a type-safe way
+  const customInstances = new WeakMap<ObjectQL, string>();
+  
   const customQL = new ObjectQL({ 
     env: 'test',
     customProperty: 'test-value' 
   });
 
-  // Add a marker to identify this instance
-  (customQL as any).customMarker = 'custom-instance';
+  // Mark this as a custom instance
+  customInstances.set(customQL, 'custom-instance');
 
   const kernel = new ObjectStackKernel([
     new ObjectQLPlugin(customQL)
@@ -59,12 +62,17 @@ async function testCustomObjectQL() {
     throw new Error('FAILED: ObjectQL not set');
   }
 
-  if ((kernel.ql as any).customMarker !== 'custom-instance') {
+  if (!customInstances.has(kernel.ql)) {
     throw new Error('FAILED: Custom ObjectQL instance not used');
   }
 
+  const marker = customInstances.get(kernel.ql);
+  if (marker !== 'custom-instance') {
+    throw new Error('FAILED: Custom ObjectQL instance marker mismatch');
+  }
+  
   console.log('✅ Custom ObjectQL instance registered correctly');
-  console.log('Custom marker:', (kernel.ql as any).customMarker);
+  console.log('Custom marker:', marker);
 }
 
 async function testMultiplePlugins() {