Refactor: Migrate to @objectstack/runtime microkernel architecture

ARCHITECTURE.md

@@ -56,19 +56,23 @@ All ObjectOS plugins must conform to this lifecycle for consistency and predicta
 
 ### ObjectOS Repository (Runtime Implementation)
 - **Location**: This repository
-- **Purpose**: Implements the runtime engine that executes ObjectQL metadata
+- **Purpose**: Implements the runtime engine and plugin ecosystem
 - **Key Packages**:
-  - `@objectos/kernel` - Core execution engine
-  - `@objectos/server` - HTTP API layer
+  - `@objectstack/runtime` - Microkernel with plugin lifecycle management
+  - `@objectos/plugin-server` - NestJS HTTP server plugin
+  - `@objectos/plugin-better-auth` - Authentication plugin
+  - `@objectos/plugin-audit-log` - Audit logging plugin
+  - `@objectos/kernel` - **DEPRECATED** (use @objectstack/runtime)
+  - `@objectos/server` - **DEPRECATED** (use @objectos/plugin-server)
 
 ## Core Architectural Principle
 
-> **"Kernel handles logic, Drivers handle data, Server handles HTTP."**
+> **"Runtime manages plugins, Plugins implement features, Drivers handle data."**
 
 This separation ensures:
 1. **Testability**: Each layer can be tested independently
-2. **Flexibility**: Swap databases without changing business logic
-3. **Scalability**: Scale HTTP layer independently from data layer
+2. **Flexibility**: Add/remove features via plugins without touching core
+3. **Scalability**: Plugins can be distributed and loaded dynamically
 4. **Maintainability**: Clear boundaries reduce coupling
 
 ## Layer 1: Metadata Protocol (ObjectQL)

MICROKERNEL_MIGRATION_SUMMARY.md

@@ -0,0 +1,231 @@
+# ObjectOS Microkernel Migration Summary
+
+## Overview
+
+This document summarizes the architectural refactoring completed to transition ObjectOS from a monolithic kernel architecture to a microkernel plugin-based architecture.
+
+**Date**: February 1, 2026  
+**Version**: 0.3.0-alpha  
+**Status**: In Progress
+
+## What Changed
+
+### Deprecated Packages
+
+1. **@objectos/kernel** (v0.2.0)
+   - **Status**: Deprecated but functional
+   - **Replacement**: `@objectstack/runtime`
+   - **Migration Path**: See [migration guide](./docs/guide/migration-from-kernel.md)
+
+2. **@objectos/server** (v0.2.0)
+   - **Status**: Deprecated but functional
+   - **Replacement**: `@objectos/plugin-server`
+   - **Migration Path**: See [migration guide](./docs/guide/migration-from-kernel.md)
+
+### New Packages
+
+1. **@objectstack/runtime** (v0.1.0)
+   - Microkernel with plugin lifecycle management
+   - Service registry and event bus
+   - Dependency resolution with topological sorting
+   - Built-in logger
+
+2. **@objectos/plugin-server** (v0.1.0)
+   - NestJS HTTP server as a runtime plugin
+   - REST, GraphQL, and WebSocket support
+   - Authentication middleware integration
+   - CORS configuration
+
+## Architecture Changes
+
+### Before (Monolithic)
+
+```
+┌────────────────────────┐
+│   @objectos/server     │  ← Standalone NestJS server
+├────────────────────────┤
+│   @objectos/kernel     │  ← Monolithic kernel
+│  • Permissions         │
+│  • Plugins             │
+│  • Metrics             │
+│  • Workflows           │
+│  • Hot Reload          │
+├────────────────────────┤
+│   @objectql/core       │
+└────────────────────────┘
+```
+
+### After (Microkernel + Plugins)
+
+```
+┌────────────────────────────────────────┐
+│          Plugin Ecosystem              │
+│                                        │
+│  @objectos/plugin-server               │  ← HTTP Server
+│  @objectos/plugin-better-auth          │  ← Auth
+│  @objectos/plugin-audit-log            │  ← Audit
+│  @objectos/plugin-permissions (TODO)   │  ← Permissions
+│  @objectos/plugin-workflow (TODO)      │  ← Workflows
+│  @objectos/plugin-metrics (TODO)       │  ← Metrics
+│                                        │
+├────────────────────────────────────────┤
+│      @objectstack/runtime              │  ← Microkernel
+│   • Plugin Lifecycle                   │
+│   • Service Registry                   │
+│   • Event Bus                          │
+│   • Dependency Resolution              │
+├────────────────────────────────────────┤
+│      @objectql/core                    │
+└────────────────────────────────────────┘
+```
+
+## Implementation Details
+
+### Files Created
+
+1. **Documentation**
+   - `/docs/guide/migration-from-kernel.md` - Complete migration guide
+   - `/docs/guide/plugin-development.md` - Plugin development guide
+   - `/packages/kernel/README.md` - Deprecation notice
+   - `/packages/server/README.md` - Deprecation notice
+   - `/packages/plugins/server/README.md` - Server plugin documentation
+
+2. **Server Plugin**
+   - `/packages/plugins/server/package.json` - Package definition
+   - `/packages/plugins/server/src/plugin.ts` - Plugin implementation
+   - `/packages/plugins/server/src/bootstrap.ts` - Bootstrap entry point
+   - `/packages/plugins/server/src/index.ts` - Public API
+   - `/packages/plugins/server/src/*` - Copied NestJS modules
+
+3. **Runtime Enhancements**
+   - Updated `/packages/runtime/src/index.ts` - Better exports
+
+### Files Modified
+
+1. **Project Configuration**
+   - `/pnpm-workspace.yaml` - Exclude deprecated packages, include runtime
+   - `/package.json` - Update scripts, remove runtime patch
+   - `/README.md` - Update architecture table
+   - `/ARCHITECTURE.md` - Update architectural principles
+
+2. **Deprecation Markers**
+   - `/packages/kernel/package.json` - Add deprecation notice
+   - `/packages/server/package.json` - Add deprecation notice
+
+## Key Benefits
+
+### 1. Modularity
+- Features are now isolated in separate plugins
+- Plugins can be enabled/disabled independently
+- Third-party plugins are easier to develop
+
+### 2. Testability
+- Test plugins in isolation
+- Mock plugins for unit testing
+- Clear plugin boundaries
+
+### 3. Maintainability
+- Reduced core complexity
+- Clear separation of concerns
+- Easier to understand and debug
+
+### 4. Extensibility
+- Plugin ecosystem for community contributions
+- Standard plugin interface
+- Dependency management
+
+### 5. Spec Compliance
+- Follows @objectstack/spec protocol
+- Consistent with ecosystem standards
+- Future-proof architecture
+
+## Migration Timeline
+
+### Phase 1: Foundation (Current)
+- ✅ Create microkernel architecture
+- ✅ Deprecate monolithic packages
+- ✅ Create server plugin
+- ✅ Write documentation
+- ⏳ Fix TypeScript compilation issues
+
+### Phase 2: Feature Migration (Next)
+- ⏳ Create permission system plugin
+- ⏳ Create workflow engine plugin
+- ⏳ Create metrics plugin
+- ⏳ Migrate hot reload to runtime core
+
+### Phase 3: Testing & Validation
+- ⏳ Unit tests for runtime
+- ⏳ Integration tests for plugins
+- ⏳ Migration testing
+- ⏳ Performance benchmarks
+
+### Phase 4: Community Migration (Future)
+- ⏳ Plugin registry
+- ⏳ Community plugin templates
+- ⏳ Plugin certification
+- ⏳ Migration tooling
+
+## Known Issues
+
+### TypeScript Compilation
+Some TypeScript errors remain in the server plugin:
+- Missing type definitions for `pg` and `better-sqlite3`
+- PluginContext compatibility issues
+- Express request type extensions
+
+**Status**: To be fixed in next iteration
+
+### Testing
+- Server plugin has not been tested yet
+- Integration tests need to be written
+- Migration path needs validation
+
+**Status**: Pending
+
+## Next Steps
+
+1. **Fix Compilation Errors** (Priority: HIGH)
+   - Add missing @types/* packages
+   - Fix PluginContext compatibility
+   - Resolve Express typing issues
+
+2. **Create Feature Plugins** (Priority: MEDIUM)
+   - Extract permission system from kernel
+   - Extract workflow engine from kernel
+   - Extract metrics from kernel
+
+3. **Testing** (Priority: HIGH)
+   - Write unit tests for runtime
+   - Write integration tests for plugins
+   - Test migration path
+
+4. **Documentation** (Priority: MEDIUM)
+   - Add more examples
+   - Create video tutorials
+   - Update API documentation
+
+## Migration Support
+
+### For Users
+- **Migration Guide**: See `/docs/guide/migration-from-kernel.md`
+- **Plugin Guide**: See `/docs/guide/plugin-development.md`
+- **Examples**: See `/packages/plugins/*/README.md`
+
+### For Contributors
+- **Architecture**: See `/ARCHITECTURE.md`
+- **Contributing**: See `/CONTRIBUTING.md`
+- **Roadmap**: See `/ROADMAP.md`
+
+## Conclusion
+
+The migration to a microkernel architecture represents a significant improvement in ObjectOS's design. While there are still some compilation issues to resolve, the foundation is solid and the benefits are clear.
+
+The plugin-based architecture provides better modularity, testability, and extensibility, making ObjectOS more suitable for enterprise use and community contributions.
+
+## References
+
+- [@objectstack/spec](https://github.com/objectstack-ai/spec)
+- [Plugin Development Guide](./docs/guide/plugin-development.md)
+- [Migration Guide](./docs/guide/migration-from-kernel.md)
+- [Runtime Documentation](./packages/runtime/README.md)

README.md

@@ -86,11 +86,12 @@ This ensures interoperability across the ObjectStack ecosystem (ObjectQL, Object
 | Package | Role | Description |
 | :--- | :--- | :--- |
 | **`@objectstack/runtime`** | **The Kernel** | Micro-kernel with plugin lifecycle and service registry. |
-| **`@objectos/kernel`** | **The Brain** | The core logic engine. Wraps ObjectQL, manages plugins, and handles the event bus. |
-| **`@objectos/server`** | **The Gateway** | NestJS application layer. Handles HTTP/WS traffic, Middlewares, and Guards. |
-| **`@objectos/plugin-auth`** | **Auth** | Authentication strategies (Local, OAuth2, Enterprise SSO). |
-| **`@objectos/plugin-workflow`** | **Logic** | Workflow engine and trigger runner. |
+| **`@objectos/plugin-server`** | **The Gateway** | NestJS HTTP server as a runtime plugin. |
+| **`@objectos/plugin-better-auth`** | **Auth** | Authentication strategies (Local, OAuth2, Enterprise SSO). |
+| **`@objectos/plugin-audit-log`** | **Audit** | Comprehensive audit logging and field history tracking. |
 | **`@objectos/presets`** | **Config** | Standard system objects (`_users`, `_roles`, `_audit_log`). |
+| **`@objectos/kernel`** | **DEPRECATED** | ⚠️ Use `@objectstack/runtime` instead |
+| **`@objectos/server`** | **DEPRECATED** | ⚠️ Use `@objectos/plugin-server` instead |
 
 ---