Update documentation and deprecate ObjectStackKernel

Copilot · hotlong · Copilot · commit b8a22bf518d8 · 2026-01-28T03:04:11.000Z
Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/runtime/README.md b/packages/runtime/README.md
@@ -4,42 +4,51 @@ ObjectStack Core Runtime & Query Engine
 
 ## Overview
 
-The runtime package provides the `ObjectStackKernel` - the central orchestrator for ObjectStack applications. It manages the application lifecycle, plugins, and the ObjectQL data engine.
+The runtime package provides the `ObjectKernel` (MiniKernel) - a highly modular, plugin-based microkernel that orchestrates ObjectStack applications. It manages the application lifecycle through a standardized plugin system with dependency injection and event hooks.
+
+### Architecture Highlights
+
+- **MiniKernel Design**: Business logic is completely separated into plugins
+- **Dependency Injection**: Service registry for inter-plugin communication
+- **Event/Hook System**: Publish-subscribe mechanism for loose coupling
+- **Lifecycle Management**: Standardized init/start/destroy phases
+- **Dependency Resolution**: Automatic topological sorting based on plugin dependencies
 
 ## Installation
 
 ```bash
 npm install @objectstack/runtime
 ```
 
-## Usage
+## Quick Start
 
-### Basic Setup
+### Basic Setup (Recommended)
 
 ```typescript
-import { ObjectStackKernel, ObjectQLPlugin } from '@objectstack/runtime';
+import { ObjectKernel, ObjectQLPlugin, DriverPlugin } from '@objectstack/runtime';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 
-const kernel = new ObjectStackKernel([
+const kernel = new ObjectKernel();
+
+kernel
   // Register ObjectQL engine
-  new ObjectQLPlugin(),
+  .use(new ObjectQLPlugin())
   
   // Add database driver
-  new InMemoryDriver(),
+  .use(new DriverPlugin(new InMemoryDriver(), 'memory'))
   
   // Add your app configurations
-  // appConfig,
-]);
+  // .use(new AppManifestPlugin(appConfig));
 
-await kernel.start();
+await kernel.bootstrap();
 ```
 
 ### Custom ObjectQL Instance
 
 If you have a separate ObjectQL implementation or need custom configuration:
 
 ```typescript
-import { ObjectStackKernel, ObjectQLPlugin, ObjectQL } from '@objectstack/runtime';
+import { ObjectKernel, ObjectQLPlugin, DriverPlugin, ObjectQL } from '@objectstack/runtime';
 
 // Create custom ObjectQL instance
 const customQL = new ObjectQL({
@@ -52,111 +61,167 @@ customQL.registerHook('beforeInsert', async (ctx) => {
   console.log(`Inserting into ${ctx.object}`);
 });
 
-const kernel = new ObjectStackKernel([
+const kernel = new ObjectKernel();
+
+kernel
   // Use your custom ObjectQL instance
-  new ObjectQLPlugin(customQL),
+  .use(new ObjectQLPlugin(customQL))
   
-  // ... other plugins
-]);
+  // Add driver
+  .use(new DriverPlugin(new InMemoryDriver(), 'memory'));
 
-await kernel.start();
+await kernel.bootstrap();
+
+// Access ObjectQL via service registry
+const objectql = kernel.getService('objectql');
 ```
 
-### Backward Compatibility
+## Architecture
 
-For backward compatibility, the kernel will automatically initialize ObjectQL if no `ObjectQLPlugin` is provided:
+### ObjectKernel (MiniKernel)
+
+The kernel provides:
+- **Plugin Lifecycle Management**: init → start → destroy phases
+- **Service Registry**: Dependency injection container
+- **Event/Hook System**: Inter-plugin communication
+- **Dependency Resolution**: Topological sort for plugin dependencies
+
+### Built-in Plugins
+
+#### ObjectQLPlugin
+Registers the ObjectQL data engine as a service.
 
 ```typescript
-// This still works, but will show a deprecation warning
-const kernel = new ObjectStackKernel([
-  new InMemoryDriver(),
-  // ... other plugins
-]);
+new ObjectQLPlugin()                           // Default instance
+new ObjectQLPlugin(customQL)                   // Custom instance
+new ObjectQLPlugin(undefined, { env: 'prod' }) // With context
 ```
 
-## Architecture
+**Services**: `'objectql'`
 
-### ObjectStackKernel
+#### DriverPlugin
+Registers a data driver with ObjectQL.
 
-The kernel is responsible for:
-- Orchestrating application lifecycle
-- Managing plugins
-- Coordinating the ObjectQL engine
-- Handling data operations
+```typescript
+new DriverPlugin(driver, 'driver-name')
+```
+
+**Dependencies**: `['com.objectstack.engine.objectql']`
+
+#### AppManifestPlugin
+Wraps ObjectStack app manifests (objectstack.config.ts) as plugins.
 
-### ObjectQLPlugin
+```typescript
+new AppManifestPlugin(appConfig)
+```
 
-The `ObjectQLPlugin` provides:
-- Explicit ObjectQL engine registration
-- Support for custom ObjectQL instances
-- Clean separation of concerns
-- Better testability
+**Dependencies**: `['com.objectstack.engine.objectql']`
 
 ## API Reference
 
-### ObjectStackKernel
+### ObjectKernel
+
+#### Methods
+- `use(plugin: Plugin)`: Register a plugin
+- `bootstrap()`: Initialize and start all plugins
+- `shutdown()`: Stop all plugins in reverse order
+- `getService<T>(name: string)`: Get a service from registry
+- `isRunning()`: Check if kernel is running
+- `getState()`: Get current kernel state
+
+### Plugin Interface
 
-#### Constructor
 ```typescript
-constructor(plugins: any[] = [])
+interface Plugin {
+  name: string;                              // Unique identifier
+  version?: string;                          // Plugin version
+  dependencies?: string[];                   // Required plugin names
+  
+  init(ctx: PluginContext): Promise<void>;   // Register services
+  start?(ctx: PluginContext): Promise<void>; // Execute business logic
+  destroy?(): Promise<void>;                  // Cleanup
+}
 ```
 
-#### Methods
-- `start()`: Initialize and start the kernel
-- `find(objectName, query)`: Query data
-- `get(objectName, id)`: Get single record
-- `create(objectName, data)`: Create record
-- `update(objectName, id, data)`: Update record
-- `delete(objectName, id)`: Delete record
-- `getMetadata(objectName)`: Get object metadata
-- `getView(objectName, viewType)`: Get UI view definition
-
-### ObjectQLPlugin
-
-#### Constructor
+### PluginContext
+
 ```typescript
-constructor(ql?: ObjectQL, hostContext?: Record<string, any>)
+interface PluginContext {
+  registerService(name: string, service: any): void;
+  getService<T>(name: string): T;
+  hook(name: string, handler: Function): void;
+  trigger(name: string, ...args: any[]): Promise<void>;
+  logger: Console;
+  getKernel?(): any;
+}
 ```
 
-#### Parameters
-- `ql` (optional): Custom ObjectQL instance
-- `hostContext` (optional): Host context configuration
-
 ## Examples
 
 See the `examples/` directory for complete examples:
 - `examples/host/` - Full server setup with Hono
 - `examples/msw-react-crud/` - Browser-based setup with MSW
 - `examples/custom-objectql-example.ts` - Custom ObjectQL instance
+- `test-mini-kernel.ts` - Comprehensive test suite
 
 ## Migration Guide
 
-### From Hardcoded ObjectQL to Plugin-Based
+### From ObjectStackKernel to ObjectKernel
 
-**Before:**
+**Before (Legacy):**
 ```typescript
-const kernel = new ObjectStackKernel([appConfig, driver]);
-```
+import { ObjectStackKernel, ObjectQLPlugin } from '@objectstack/runtime';
 
-**After (Recommended):**
-```typescript
 const kernel = new ObjectStackKernel([
   new ObjectQLPlugin(),
-  appConfig, 
+  appConfig,
   driver
 ]);
+
+await kernel.start();
 ```
 
-**After (Custom Instance):**
+**After (Recommended):**
 ```typescript
-const customQL = new ObjectQL({ /* config */ });
-const kernel = new ObjectStackKernel([
-  new ObjectQLPlugin(customQL),
-  appConfig, 
-  driver
-]);
+import { ObjectKernel, ObjectQLPlugin, DriverPlugin, AppManifestPlugin } from '@objectstack/runtime';
+
+const kernel = new ObjectKernel();
+
+kernel
+  .use(new ObjectQLPlugin())
+  .use(new DriverPlugin(driver, 'memory'))
+  .use(new AppManifestPlugin(appConfig));
+
+await kernel.bootstrap();
 ```
 
+## Benefits of MiniKernel
+
+1. **True Modularity**: Each plugin is independent and reusable
+2. **Testability**: Mock services easily in tests
+3. **Flexibility**: Load plugins conditionally
+4. **Extensibility**: Add new plugins without modifying kernel
+5. **Clear Dependencies**: Explicit dependency declarations
+6. **Better Architecture**: Separation of concerns
+
+## Best Practices
+
+1. **Keep plugins focused**: One responsibility per plugin
+2. **Use services**: Share functionality via service registry
+3. **Declare dependencies**: Make plugin requirements explicit
+4. **Use hooks**: Decouple plugins with event system
+5. **Handle errors**: Implement proper error handling in lifecycle methods
+
+## Documentation
+
+- [MiniKernel Guide](../../MINI_KERNEL_GUIDE.md) - Complete API documentation and patterns
+- [MiniKernel Architecture](../../MINI_KERNEL_ARCHITECTURE.md) - Architecture diagrams and flows
+- [MiniKernel Implementation](../../MINI_KERNEL_IMPLEMENTATION.md) - Implementation details
+
+## Legacy Support
+
+The `ObjectStackKernel` is still available for backward compatibility but is deprecated. New projects should use `ObjectKernel`.
+
 ## License
 
-MIT
+Apache-2.0
diff --git a/packages/runtime/src/kernel.ts b/packages/runtime/src/kernel.ts
@@ -2,10 +2,36 @@ import { ServiceObject } from '@objectstack/spec/data';
 import { SchemaRegistry, ObjectQL } from '@objectstack/objectql';
 
 /**
- * ObjectStack Kernel (Microkernel)
+ * ObjectStack Kernel (Legacy)
  * 
- * The central container orchestrating the application lifecycle,
- * plugins, and the core ObjectQL engine.
+ * @deprecated Use ObjectKernel (MiniKernel) instead for better modularity and plugin architecture.
+ * This class is kept for backward compatibility but new projects should use ObjectKernel.
+ * 
+ * @see ObjectKernel - The new MiniKernel implementation
+ * @see MINI_KERNEL_GUIDE.md - Complete guide to the new architecture
+ * 
+ * The legacy kernel orchestrates the application lifecycle,
+ * plugins, and the core ObjectQL engine, but with less modularity
+ * than the new ObjectKernel implementation.
+ * 
+ * Migration example:
+ * ```typescript
+ * // Old (deprecated):
+ * const kernel = new ObjectStackKernel([
+ *   new ObjectQLPlugin(),
+ *   appConfig,
+ *   driver
+ * ]);
+ * await kernel.start();
+ * 
+ * // New (recommended):
+ * const kernel = new ObjectKernel();
+ * kernel
+ *   .use(new ObjectQLPlugin())
+ *   .use(new DriverPlugin(driver, 'memory'))
+ *   .use(new AppManifestPlugin(appConfig));
+ * await kernel.bootstrap();
+ * ```
  */
 export class ObjectStackKernel {
   public ql?: ObjectQL; // Will be set by ObjectQLPlugin or fallback initialization
