docs: Update documentation for Phase 3 plugin architecture and kernel integration

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

Author: Copilot

packages/foundation/core/README.md

@@ -1,22 +1,35 @@
 # @objectql/core
 
-The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, transaction management, and **metadata-driven validation**.
+The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, transaction management, and **metadata-driven validation**. As of version 4.0.0, it wraps the **ObjectStackKernel** for plugin architecture and lifecycle management.
 
 ## Features
 
-- **Unified Query Language**: A generic way to query data across different databases (SQL, Mongo, etc.).
-- **Repository Pattern**: `ObjectRepository` for managing object records.
-- **Driver Agnostic**: Abstraction layer for database drivers.
-- **Dynamic Schema**: Loads object definitions from metadata.
-- **Hooks & Actions**: Runtime logic injection.
-- **Validation Engine**: Metadata-driven validation with field-level, cross-field, and state machine rules.
+- **Plugin Architecture**: Built on top of `@objectstack/runtime` with kernel-based plugin system
+- **Unified Query Language**: A generic way to query data across different databases (SQL, Mongo, etc.)
+- **Repository Pattern**: `ObjectRepository` for managing object records
+- **Driver Agnostic**: Abstraction layer for database drivers
+- **Dynamic Schema**: Loads object definitions from metadata
+- **Hooks & Actions**: Runtime logic injection
+- **Validation Engine**: Metadata-driven validation with field-level, cross-field, and state machine rules
+- **Formula Engine**: Computed fields with dynamic formulas
+- **AI Integration**: Built-in AI agent capabilities
 
 ## Installation
 
 ```bash
-npm install @objectql/core @objectql/types
+npm install @objectql/core @objectql/types @objectstack/runtime @objectstack/spec
 ```
 
+## Architecture
+
+ObjectQL now wraps the `ObjectStackKernel` from `@objectstack/runtime`, providing:
+
+- **Kernel-based lifecycle management**: Initialization, startup, and shutdown
+- **Plugin system**: Extensible architecture with `ObjectQLPlugin`
+- **Enhanced features**: Repository, Validator, Formula, and AI capabilities as plugins
+
+See [RUNTIME_INTEGRATION.md](./RUNTIME_INTEGRATION.md) for detailed architecture documentation.
+
 ## Usage
 
 ### Basic Setup
@@ -31,7 +44,7 @@ const objectql = new ObjectQL({
     }
 });
 
-await objectql.init();
+await objectql.init(); // Initializes the kernel and all plugins
 
 // Use context for operations
 const ctx = objectql.createContext({ userId: 'u-1' });
@@ -40,6 +53,15 @@ const projects = await ctx.object('project').find({
 });
 ```
 
+### Accessing the Kernel
+
+For advanced use cases, you can access the underlying kernel:
+
+```typescript
+const kernel = objectql.getKernel();
+// Use kernel methods if needed
+```
+
 ### Validation System
 
 The validation system allows you to define validation rules in your object metadata and execute them programmatically.

packages/foundation/core/RUNTIME_INTEGRATION.md

@@ -4,39 +4,63 @@ This document explains the integration of `@objectstack/runtime` and `@objectsta
 
 ## Overview
 
-As of version 3.0.1, ObjectQL core natively uses the ObjectStack runtime packages:
+As of version 4.0.0, ObjectQL core uses the ObjectStack runtime packages with plugin architecture:
 
-- **@objectstack/spec@0.1.2**: Protocol specification with standard `DriverInterface`
-- **@objectstack/objectql@0.1.1**: Core ObjectQL engine with driver management
-- **@objectstack/runtime@0.1.1**: Runtime kernel with application lifecycle orchestration
+- **@objectstack/spec@0.2.0**: Protocol specification with standard `DriverInterface`
+- **@objectstack/objectql@0.2.0**: Core ObjectQL engine with driver management
+- **@objectstack/runtime@0.2.0**: Runtime kernel with application lifecycle orchestration and plugin system
 
 ## Architecture
 
 ### Package Relationship
 
 ```
 @objectql/core (this package)
+├── Wraps ObjectStackKernel from @objectstack/runtime
+├── Implements ObjectQLPlugin for enhanced features
 ├── Uses @objectstack/objectql for driver management
 ├── Natively uses @objectstack/spec.DriverInterface (no wrapper)
 └── Re-exports types from @objectstack/runtime
 ```
 
-### Driver Management Integration
+### Plugin Architecture (v4.0.0)
 
-**Breaking Change (v3.0.1):** The core package now **natively uses** `DriverInterface` from `@objectstack/spec`:
+**Breaking Change (v4.0.0):** The core package now **wraps `ObjectStackKernel`** and uses a plugin architecture:
 
 ```typescript
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL, ObjectQLPlugin } from '@objectql/core';
 import type { DriverInterface } from '@objectstack/spec';
 
-// Drivers must implement DriverInterface from @objectstack/spec
+// ObjectQL now wraps ObjectStackKernel internally
 const app = new ObjectQL({
     datasources: {
         default: myDriver  // Must be DriverInterface
     }
 });
 
-await app.init();
+// Access the kernel if needed
+const kernel = app.getKernel();
+
+await app.init(); // This calls kernel.start() internally
+```
+
+### ObjectQLPlugin
+
+The new `ObjectQLPlugin` class implements the `RuntimePlugin` interface from `@objectstack/runtime`:
+
+```typescript
+import { ObjectQLPlugin, ObjectQLPluginConfig } from '@objectql/core';
+
+// Configure the plugin
+const plugin = new ObjectQLPlugin({
+    enableRepository: true,
+    enableValidator: true,
+    enableFormulas: true,
+    enableAI: true
+});
+
+// The plugin is automatically registered when you create an ObjectQL instance
+const app = new ObjectQL({ datasources: {} });
 ```
 
 ### Type Exports
@@ -76,6 +100,7 @@ The current `ObjectQL` class in this package is a **production-ready, feature-ri
 - Repository pattern
 - Formula engine
 - AI integration
+- **Wraps ObjectStackKernel for plugin architecture**
 - **Native driver management via @objectstack/objectql**
 
 The `ObjectQLEngine` from `@objectstack/objectql` is a **simpler, lightweight** implementation suitable for:
@@ -84,6 +109,46 @@ The `ObjectQLEngine` from `@objectstack/objectql` is a **simpler, lightweight**
 - Simple driver management
 - Minimal runtime overhead
 
+### Kernel Integration
+
+ObjectQL now wraps the `ObjectStackKernel` to provide plugin architecture and lifecycle management:
+
+```typescript
+// In @objectql/core
+import { ObjectStackKernel } from '@objectstack/runtime';
+import { ObjectQLPlugin } from './plugin';
+
+export class ObjectQL implements IObjectQL {
+    private kernel: ObjectStackKernel;
+    private kernelPlugins: any[] = [];
+    
+    constructor(config: ObjectQLConfig) {
+        // Add the ObjectQL plugin to provide enhanced features
+        this.kernelPlugins.push(new ObjectQLPlugin());
+        
+        // Create the kernel instance
+        this.kernel = new ObjectStackKernel(this.kernelPlugins);
+    }
+    
+    async init() {
+        console.log('[ObjectQL] Initializing with ObjectStackKernel...');
+        
+        // Start the kernel first - this will install and start all plugins
+        await this.kernel.start();
+        
+        // Continue with legacy initialization...
+    }
+    
+    /**
+     * Get the underlying ObjectStackKernel instance
+     * for advanced usage scenarios
+     */
+    getKernel(): ObjectStackKernel {
+        return this.kernel;
+    }
+}
+```
+
 ### Driver Management (No Compatibility Layer)
 
 ObjectQL now directly uses drivers conforming to `@objectstack/spec.DriverInterface`:
@@ -174,12 +239,42 @@ app.registerDriver('mydb', new MyCustomDriver(), false);
 
 ## Breaking Changes
 
+### v4.0.0: Plugin Architecture
+
+**What Changed:**
+- `ObjectQL` now wraps `ObjectStackKernel` from `@objectstack/runtime`
+- New `ObjectQLPlugin` class implements `RuntimePlugin` interface
+- Initialization process now calls `kernel.start()` which installs and starts all plugins
+- Dependencies updated to `@objectstack/*@0.2.0`
+- New `getKernel()` method provides access to the underlying kernel
+
+**Migration Guide:**
+
+Your existing code should continue to work without changes:
+```typescript
+import { ObjectQL } from '@objectql/core';
+import { MyDriver } from './my-driver';
+
+const app = new ObjectQL({
+    datasources: {
+        default: new MyDriver()
+    }
+});
+
+await app.init(); // Now calls kernel.start() internally
+```
+
+If you need kernel access:
+```typescript
+const kernel = app.getKernel();
+// Use kernel methods if needed
+```
+
 ### v3.0.1: Native DriverInterface Adoption
 
 **What Changed:**
 - `ObjectQLConfig.datasources` now requires `Record<string, DriverInterface>` (from `@objectstack/spec`)
 - Removed compatibility wrapper for old `Driver` type
-- `app.registerDriver()` now accepts `DriverInterface` instead of legacy `Driver`
 - `app.datasource()` now returns `DriverInterface`
 - Driver lifecycle is fully managed by ObjectStack engine
 

packages/foundation/core/jest.config.js

@@ -12,6 +12,7 @@ module.exports = {
   testMatch: ['**/test/**/*.test.ts'],
   moduleNameMapper: {
     '^@objectql/(.*)$': '<rootDir>/../$1/src',
+    '^@objectstack/runtime$': '<rootDir>/test/__mocks__/@objectstack/runtime.ts',
   },
   transform: {
     '^.+\\.ts$': ['ts-jest', {

packages/foundation/core/test/__mocks__/@objectstack/runtime.ts

@@ -0,0 +1,61 @@
+/**
+ * Mock for @objectstack/runtime
+ * This mock is needed because the npm package has issues with Jest
+ * and we want to focus on testing ObjectQL's logic, not the kernel integration.
+ */
+
+export class ObjectStackKernel {
+    public ql: any = null;
+    
+    constructor(plugins: any[] = []) {
+        // Mock implementation
+    }
+    
+    async start(): Promise<void> {
+        // Mock implementation
+    }
+    
+    async seed(): Promise<void> {
+        // Mock implementation
+    }
+    
+    async find(objectName: string, query: any): Promise<{ value: Record<string, any>[]; count: number }> {
+        return { value: [], count: 0 };
+    }
+    
+    async get(objectName: string, id: string): Promise<Record<string, any>> {
+        return {};
+    }
+    
+    async create(objectName: string, data: any): Promise<Record<string, any>> {
+        return data;
+    }
+    
+    async update(objectName: string, id: string, data: any): Promise<Record<string, any>> {
+        return data;
+    }
+    
+    async delete(objectName: string, id: string): Promise<boolean> {
+        return true;
+    }
+    
+    getMetadata(objectName: string): any {
+        return {};
+    }
+    
+    getView(objectName: string, viewType?: 'list' | 'form'): any {
+        return null;
+    }
+}
+
+export class ObjectStackRuntimeProtocol {}
+
+export interface RuntimeContext {
+    engine: ObjectStackKernel;
+}
+
+export interface RuntimePlugin {
+    name: string;
+    install?: (ctx: RuntimeContext) => void | Promise<void>;
+    onStart?: (ctx: RuntimeContext) => void | Promise<void>;
+}

packages/foundation/core/test/app.test.ts

@@ -6,24 +6,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// Mock the ObjectStackKernel before importing ObjectQL
-jest.mock('@objectstack/runtime', () => {
-    return {
-        ObjectStackKernel: jest.fn().mockImplementation(() => ({
-            ql: null,
-            start: jest.fn().mockResolvedValue(undefined),
-            seed: jest.fn().mockResolvedValue(undefined),
-            find: jest.fn().mockResolvedValue({ value: [], count: 0 }),
-            get: jest.fn().mockResolvedValue({}),
-            create: jest.fn().mockResolvedValue({}),
-            update: jest.fn().mockResolvedValue({}),
-            delete: jest.fn().mockResolvedValue(true),
-            getMetadata: jest.fn().mockReturnValue({}),
-            getView: jest.fn().mockReturnValue(null),
-        })),
-    };
-});
-
 import { ObjectQL } from '../src/app';
 import { MockDriver } from './mock-driver';
 import { ObjectConfig, HookContext, ActionContext, Metadata } from '@objectql/types';

packages/foundation/core/test/setup-mocks.ts

@@ -0,0 +1,31 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Mock for @objectstack/runtime
+ * This mock is needed because the npm package has issues with Jest
+ * and we want to focus on testing ObjectQL's logic, not the kernel integration.
+ */
+export function setupObjectStackRuntimeMock() {
+    jest.mock('@objectstack/runtime', () => {
+        return {
+            ObjectStackKernel: jest.fn().mockImplementation(() => ({
+                ql: null,
+                start: jest.fn().mockResolvedValue(undefined),
+                seed: jest.fn().mockResolvedValue(undefined),
+                find: jest.fn().mockResolvedValue({ value: [], count: 0 }),
+                get: jest.fn().mockResolvedValue({}),
+                create: jest.fn().mockResolvedValue({}),
+                update: jest.fn().mockResolvedValue({}),
+                delete: jest.fn().mockResolvedValue(true),
+                getMetadata: jest.fn().mockReturnValue({}),
+                getView: jest.fn().mockReturnValue(null),
+            })),
+        };
+    });
+}