Define RuntimePlugin interface and update protocol plugins for conformance

RUNTIME_PLUGIN_IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,131 @@
+# RuntimePlugin Interface Implementation - Summary
+
+## Issue
+The GraphQL, OData V4, and JSON-RPC protocol plugins were not formally implementing a standard `RuntimePlugin` interface, leading to architectural inconsistency issues.
+
+## Solution
+We have successfully implemented the `RuntimePlugin` interface specification and updated all three protocol plugins to conform to it.
+
+## Changes Made
+
+### 1. RuntimePlugin Interface Definition (`@objectql/types`)
+
+Created `/packages/foundation/types/src/plugin.ts` defining:
+
+#### RuntimePlugin Interface
+```typescript
+export interface RuntimePlugin {
+  name: string;
+  version?: string;
+  install?(ctx: RuntimeContext): void | Promise<void>;
+  onStart?(ctx: RuntimeContext): void | Promise<void>;
+  onStop?(ctx: RuntimeContext): void | Promise<void>;
+}
+```
+
+#### RuntimeContext Interface
+```typescript
+export interface RuntimeContext {
+  engine: any;
+  getKernel?: () => any;
+}
+```
+
+### 2. Protocol Plugin Updates
+
+#### GraphQL Plugin (`@objectql/protocol-graphql`)
+- ✅ Implements `RuntimePlugin` interface
+- ✅ Removed dependency on `@objectstack/runtime`
+- ✅ Added helper methods for metadata and CRUD operations
+- ✅ Direct engine access via RuntimeContext
+
+#### OData V4 Plugin (`@objectql/protocol-odata-v4`)
+- ✅ Implements `RuntimePlugin` interface
+- ✅ Removed dependency on `@objectstack/runtime`
+- ✅ Added helper methods for metadata and CRUD operations
+- ✅ Direct engine access via RuntimeContext
+
+#### JSON-RPC Plugin (`@objectql/protocol-json-rpc`)
+- ✅ Implements `RuntimePlugin` interface
+- ✅ Removed dependency on `@objectstack/runtime`
+- ✅ Added helper methods for metadata and CRUD operations
+- ✅ Direct engine access via RuntimeContext
+
+### 3. Package Dependencies
+
+Updated all three plugin `package.json` files to:
+- Remove `@objectstack/runtime` dependency
+- Use only `@objectql/types` for interface definitions
+
+### 4. Tests
+
+Added comprehensive test suite in `/packages/foundation/types/test/plugin.test.ts`:
+- RuntimePlugin interface conformance tests
+- RuntimeContext functionality tests
+- Lifecycle hook execution order tests
+- Sync/async hook support tests
+
+### 5. Documentation
+
+Updated `/packages/protocols/README.md`:
+- Documented RuntimePlugin interface
+- Documented RuntimeContext
+- Updated plugin implementation pattern
+- Added Engine API documentation
+- Removed references to deprecated ObjectStackRuntimeProtocol
+
+## Architecture Compliance
+
+### ✅ Standard Lifecycle Hooks
+All plugins now implement:
+1. **install(ctx)** - Called during kernel initialization
+2. **onStart(ctx)** - Called when kernel starts
+3. **onStop(ctx)** - Called when kernel stops
+
+### ✅ Consistent Interface
+All plugins implement the same `RuntimePlugin` interface from `@objectql/types`, ensuring:
+- Uniform plugin architecture
+- Predictable lifecycle management
+- Easy plugin discovery and validation
+- Type-safe plugin development
+
+### ✅ Direct Engine Access
+Plugins no longer depend on a separate protocol bridge layer. Instead:
+- They access the kernel/engine directly via RuntimeContext
+- They implement their own helper methods for common operations
+- They maintain full control over their data access patterns
+
+## Impact
+
+### Architecture Consistency ✅
+- All protocol plugins follow the same interface
+- Clear lifecycle management
+- Consistent error handling
+
+### Plugin Extensibility ✅
+- Easy to add new protocol plugins
+- Clear contract to implement
+- Type-safe development
+
+### Maintenance Cost ✅
+- Reduced dependency on non-existent packages
+- Simpler architecture
+- Better testability
+
+## Testing Results
+
+- ✅ RuntimePlugin interface tests pass
+- ✅ Existing plugin lifecycle tests remain valid
+- ✅ No breaking changes to plugin APIs
+- ✅ TypeScript compilation successful (modulo external dependencies)
+
+## Next Steps
+
+The implementation is complete and ready for use. Protocol plugins can now be:
+1. Instantiated with their configuration
+2. Passed to the kernel/runtime
+3. Initialized via the install hook
+4. Started via the onStart hook
+5. Stopped via the onStop hook
+
+All three plugins (GraphQL, OData V4, JSON-RPC) are now fully compliant with the ObjectStack RuntimePlugin specification.

packages/foundation/types/src/index.ts

@@ -37,3 +37,4 @@ export * from './workflow';
 export * from './report';
 export * from './form';
 export * from './formula';
+export * from './plugin';

packages/foundation/types/src/plugin.ts

@@ -0,0 +1,132 @@
+/**
+ * ObjectQL Plugin System
+ * 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.
+ */
+
+/**
+ * Runtime context passed to plugin lifecycle hooks
+ * 
+ * This context provides access to the kernel/engine instance
+ * and allows plugins to interact with the ObjectStack runtime.
+ */
+export interface RuntimeContext {
+    /**
+     * The ObjectStack kernel/engine instance
+     * 
+     * This provides access to:
+     * - metadata registry
+     * - hook manager
+     * - action manager
+     * - CRUD operations
+     */
+    engine: any; // Using 'any' to avoid circular dependency
+
+    /**
+     * Get the kernel instance (alternative accessor)
+     * Some implementations may use getKernel() instead of engine
+     */
+    getKernel?: () => any;
+}
+
+/**
+ * RuntimePlugin Interface
+ * 
+ * Defines the standard plugin contract for ObjectStack/ObjectQL ecosystem.
+ * All plugins (protocol adapters, data drivers, feature extensions) should
+ * implement this interface to ensure consistent lifecycle management.
+ * 
+ * Lifecycle Order:
+ * 1. install() - Called during kernel initialization
+ * 2. onStart() - Called when kernel starts
+ * 3. onStop() - Called when kernel stops/shuts down
+ * 
+ * @example
+ * ```typescript
+ * export class MyPlugin implements RuntimePlugin {
+ *   name = '@myorg/my-plugin';
+ *   version = '1.0.0';
+ *   
+ *   async install(ctx: RuntimeContext): Promise<void> {
+ *     // Register hooks, load configuration
+ *     console.log('Plugin installed');
+ *   }
+ *   
+ *   async onStart(ctx: RuntimeContext): Promise<void> {
+ *     // Start servers, connect to services
+ *     console.log('Plugin started');
+ *   }
+ *   
+ *   async onStop(ctx: RuntimeContext): Promise<void> {
+ *     // Cleanup resources, disconnect
+ *     console.log('Plugin stopped');
+ *   }
+ * }
+ * ```
+ */
+export interface RuntimePlugin {
+    /**
+     * Unique plugin identifier
+     * 
+     * Should follow npm package naming convention
+     * Examples: '@objectql/plugin-security', '@myorg/my-plugin'
+     */
+    name: string;
+
+    /**
+     * Plugin version (semantic versioning)
+     * 
+     * Optional but recommended for debugging and compatibility tracking
+     * Example: '1.0.0', '2.1.3-beta'
+     */
+    version?: string;
+
+    /**
+     * Install hook - called during kernel initialization
+     * 
+     * Use this phase to:
+     * - Register hooks and event handlers
+     * - Initialize plugin state
+     * - Load configuration
+     * - Register metadata (objects, fields, actions)
+     * - Validate dependencies
+     * 
+     * This is called BEFORE the kernel starts, so services may not be available yet.
+     * 
+     * @param ctx - Runtime context with access to kernel/engine
+     */
+    install?(ctx: RuntimeContext): void | Promise<void>;
+
+    /**
+     * Start hook - called when kernel starts
+     * 
+     * Use this phase to:
+     * - Start background processes (servers, workers, schedulers)
+     * - Connect to external services (databases, APIs, message queues)
+     * - Initialize runtime resources
+     * - Perform health checks
+     * 
+     * This is called AFTER install() and AFTER all plugins are installed.
+     * 
+     * @param ctx - Runtime context with access to kernel/engine
+     */
+    onStart?(ctx: RuntimeContext): void | Promise<void>;
+
+    /**
+     * Stop hook - called when kernel stops/shuts down
+     * 
+     * Use this phase to:
+     * - Stop background processes
+     * - Disconnect from external services
+     * - Cleanup resources (file handles, connections, timers)
+     * - Flush pending operations
+     * - Save state if needed
+     * 
+     * This is called during graceful shutdown. Ensure cleanup completes quickly.
+     * 
+     * @param ctx - Runtime context with access to kernel/engine
+     */
+    onStop?(ctx: RuntimeContext): void | Promise<void>;
+}