@objectstack/core 0.9.1 → 0.9.2

package/{ENHANCED_FEATURES.md → ADVANCED_FEATURES.md}

@@ -1,10 +1,10 @@
-# Enhanced ObjectKernel - Advanced Plugin Features
+# ObjectKernel - Advanced Plugin Features
 
-This document describes the enhanced features added to ObjectKernel for production-grade plugin management.
+This document describes the advanced features of ObjectKernel for production-grade plugin management.
 
 ## Overview
 
-The `EnhancedObjectKernel` extends the basic `ObjectKernel` with enterprise-grade features for plugin lifecycle management, dependency injection, and operational resilience.
+The `ObjectKernel` (formerly `EnhancedObjectKernel`) provides enterprise-grade features for plugin lifecycle management, dependency injection, and operational resilience.
 
 ## Features
 
@@ -13,9 +13,9 @@ The `EnhancedObjectKernel` extends the basic `ObjectKernel` with enterprise-grad
 Async plugin loading with comprehensive validation:
 
 ```typescript
-import { EnhancedObjectKernel, PluginMetadata } from '@objectstack/core';
+import { ObjectKernel, PluginMetadata } from '@objectstack/core';
 
-const kernel = new EnhancedObjectKernel({
+const kernel = new ObjectKernel({
   logger: { level: 'info' },
   defaultStartupTimeout: 30000,  // 30 seconds
   gracefulShutdown: true,
@@ -242,7 +242,7 @@ for (const [pluginName, startTime] of metrics) {
 Properly cleanup resources on shutdown:
 
 ```typescript
-const kernel = new EnhancedObjectKernel({
+const kernel = new ObjectKernel({
   gracefulShutdown: true,
   shutdownTimeout: 60000  // 60 second timeout
 });
@@ -309,25 +309,25 @@ const plugin: PluginMetadata = {
 };
 ```
 
-## Migration from ObjectKernel
+## Migration from LiteKernel
 
-To migrate from `ObjectKernel` to `EnhancedObjectKernel`:
+To migrate from `LiteKernel` to `ObjectKernel`:
 
 ```typescript
 // Before
-import { ObjectKernel } from '@objectstack/core';
-const kernel = new ObjectKernel();
+import { LiteKernel } from '@objectstack/core';
+const kernel = new LiteKernel();
 
 // After
-import { EnhancedObjectKernel } from '@objectstack/core';
-const kernel = new EnhancedObjectKernel({
+import { ObjectKernel } from '@objectstack/core';
+const kernel = new ObjectKernel({
   logger: { level: 'info' },
   gracefulShutdown: true,
   rollbackOnFailure: true
 });
 ```
 
-Both kernels are compatible - `EnhancedObjectKernel` is a superset of `ObjectKernel`.
+Both kernels adhere to the same `Plugin` interface, but `ObjectKernel` supports advanced features like Rollback, Sandbox, and Hot Reload.
 
 ## Best Practices
 

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @objectstack/core
 
+## 0.9.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@0.9.2
+
 ## 0.9.1
 
 ### Patch Changes

package/PHASE2_IMPLEMENTATION.md

@@ -0,0 +1,388 @@
+# ObjectStack Phase 2 Implementation
+
+This document describes the Phase 2 implementation of the ObjectStack Microkernel and Plugin Architecture Improvement Plan.
+
+## Overview
+
+Phase 2 implements the core runtime features for advanced plugin lifecycle management, dependency resolution, and security sandboxing. These components build upon the protocol definitions from Phase 1 and provide production-ready implementations.
+
+## Components
+
+### 1. Health Monitor (`health-monitor.ts`)
+
+The Health Monitor provides real-time health checking and auto-recovery for plugins.
+
+**Features:**
+- Configurable health check intervals
+- Automatic failure detection with thresholds
+- Auto-restart with backoff strategies (fixed, linear, exponential)
+- Health status tracking (healthy, degraded, unhealthy, failed, recovering, unknown)
+- Metrics collection (uptime, memory, CPU, connections, error rate)
+
+**Usage:**
+
+```typescript
+import { PluginHealthMonitor } from '@objectstack/core';
+
+const monitor = new PluginHealthMonitor(logger);
+
+// Register a plugin for monitoring
+monitor.registerPlugin('my-plugin', {
+  interval: 30000,           // Check every 30 seconds
+  timeout: 5000,             // 5 second timeout
+  failureThreshold: 3,       // Mark unhealthy after 3 failures
+  successThreshold: 1,       // Mark healthy after 1 success
+  autoRestart: true,         // Auto-restart on failure
+  maxRestartAttempts: 3,     // Max 3 restart attempts
+  restartBackoff: 'exponential',
+});
+
+// Start monitoring
+monitor.startMonitoring('my-plugin', pluginInstance);
+
+// Get health status
+const status = monitor.getHealthStatus('my-plugin');
+const report = monitor.getHealthReport('my-plugin');
+```
+
+### 2. Hot Reload Manager (`hot-reload.ts`)
+
+The Hot Reload Manager enables zero-downtime plugin updates with state preservation.
+
+**Features:**
+- State preservation strategies (memory, disk, distributed, none)
+- File watching integration points
+- Debounced reload scheduling
+- Graceful shutdown with configurable timeout
+- Before/after reload hooks
+- State checksum verification
+
+**Usage:**
+
+```typescript
+import { HotReloadManager } from '@objectstack/core';
+
+const hotReload = new HotReloadManager(logger);
+
+// Register plugin for hot reload
+hotReload.registerPlugin('my-plugin', {
+  enabled: true,
+  watchPatterns: ['src/**/*.ts'],
+  debounceDelay: 1000,
+  preserveState: true,
+  stateStrategy: 'memory',
+  shutdownTimeout: 30000,
+  beforeReload: ['plugin:beforeReload'],
+  afterReload: ['plugin:afterReload'],
+});
+
+// Trigger reload
+await hotReload.reloadPlugin(
+  'my-plugin',
+  pluginInstance,
+  '1.2.0',
+  () => ({ /* current state */ }),
+  (state) => { /* restore state */ }
+);
+```
+
+### 3. Dependency Resolver (`dependency-resolver.ts`)
+
+The Dependency Resolver provides semantic versioning and dependency management.
+
+**Features:**
+- Full SemVer parsing and comparison
+- Version constraint matching (^, ~, >=, <=, <, >, -, *, latest)
+- Topological sorting (Kahn's algorithm)
+- Circular dependency detection
+- Version conflict detection
+- Compatibility level assessment
+- Best version selection
+
+**Usage:**
+
+```typescript
+import { 
+  SemanticVersionManager, 
+  DependencyResolver 
+} from '@objectstack/core';
+
+// Parse and compare versions
+const v1 = SemanticVersionManager.parse('1.2.3');
+const v2 = SemanticVersionManager.parse('1.3.0');
+const cmp = SemanticVersionManager.compare(v1, v2); // -1
+
+// Check if version satisfies constraint
+const satisfies = SemanticVersionManager.satisfies(v1, '^1.0.0'); // true
+
+// Get compatibility level
+const compat = SemanticVersionManager.getCompatibilityLevel(v1, v2);
+// 'backward-compatible'
+
+// Resolve dependencies
+const resolver = new DependencyResolver(logger);
+
+const plugins = new Map([
+  ['core', { dependencies: [] }],
+  ['plugin-a', { dependencies: ['core'] }],
+  ['plugin-b', { dependencies: ['core', 'plugin-a'] }],
+]);
+
+const order = resolver.resolve(plugins);
+// ['core', 'plugin-a', 'plugin-b']
+
+// Detect conflicts
+const conflicts = resolver.detectConflicts(pluginsWithVersions);
+
+// Find best version
+const best = resolver.findBestVersion(
+  ['1.0.0', '1.1.0', '1.2.0', '2.0.0'],
+  ['^1.0.0', '>=1.1.0']
+);
+// '1.2.0'
+```
+
+### 4. Permission Manager (`security/permission-manager.ts`)
+
+The Permission Manager enforces fine-grained access control for plugins.
+
+**Features:**
+- Resource-level permissions (data, UI, system, storage, network, process)
+- Action-based access control (create, read, update, delete, execute, etc.)
+- Permission scopes (global, tenant, user, resource, plugin)
+- Grant/revoke mechanisms
+- Permission expiration
+- Required vs optional permissions
+- Field-level access control
+
+**Usage:**
+
+```typescript
+import { PluginPermissionManager } from '@objectstack/core/security';
+
+const permManager = new PluginPermissionManager(logger);
+
+// Register permissions
+permManager.registerPermissions('my-plugin', {
+  permissions: [
+    {
+      id: 'read-customer-data',
+      resource: 'data.object',
+      actions: ['read'],
+      scope: 'plugin',
+      description: 'Read customer data',
+      required: true,
+      filter: {
+        resourceIds: ['customer'],
+        fields: ['name', 'email'],
+      },
+    },
+  ],
+  defaultGrant: 'prompt',
+});
+
+// Grant permission
+permManager.grantPermission('my-plugin', 'read-customer-data', 'admin');
+
+// Check access
+const result = permManager.checkAccess(
+  'my-plugin',
+  'data.object',
+  'read',
+  'customer'
+);
+
+if (result.allowed) {
+  // Proceed with operation
+}
+
+// Check all required permissions
+const hasAll = permManager.hasAllRequiredPermissions('my-plugin');
+```
+
+### 5. Sandbox Runtime (`security/sandbox-runtime.ts`)
+
+The Sandbox Runtime provides isolated execution environments with resource limits.
+
+**Features:**
+- Multiple isolation levels (none, minimal, standard, strict, paranoid)
+- File system access control (allowed/denied paths)
+- Network access control (allowed/blocked hosts)
+- Process spawning control
+- Environment variable access control
+- Resource limit enforcement (memory, CPU, connections)
+- Resource usage monitoring
+
+**Usage:**
+
+```typescript
+import { PluginSandboxRuntime } from '@objectstack/core/security';
+
+const sandbox = new PluginSandboxRuntime(logger);
+
+// Create sandbox
+const context = sandbox.createSandbox('my-plugin', {
+  enabled: true,
+  level: 'standard',
+  filesystem: {
+    mode: 'restricted',
+    allowedPaths: ['/app/plugins/my-plugin'],
+    deniedPaths: ['/etc', '/root'],
+  },
+  network: {
+    mode: 'restricted',
+    allowedHosts: ['api.example.com'],
+    blockedHosts: ['malicious.com'],
+    maxConnections: 10,
+  },
+  process: {
+    allowSpawn: false,
+  },
+  memory: {
+    maxHeap: 100 * 1024 * 1024, // 100 MB
+  },
+});
+
+// Check resource access
+const fileAccess = sandbox.checkResourceAccess(
+  'my-plugin',
+  'file',
+  '/app/plugins/my-plugin/data.json'
+);
+
+const netAccess = sandbox.checkResourceAccess(
+  'my-plugin',
+  'network',
+  'https://api.example.com/data'
+);
+
+// Check resource limits
+const { withinLimits, violations } = sandbox.checkResourceLimits('my-plugin');
+
+// Get resource usage
+const usage = sandbox.getResourceUsage('my-plugin');
+```
+
+### 6. Security Scanner (`security/security-scanner.ts`)
+
+The Security Scanner performs comprehensive security analysis of plugins.
+
+**Features:**
+- Code vulnerability scanning
+- Dependency vulnerability detection (CVE database integration)
+- Malware pattern detection
+- License compliance checking
+- Configuration security analysis
+- Security scoring (0-100)
+- Issue categorization (critical, high, medium, low, info)
+
+**Usage:**
+
+```typescript
+import { PluginSecurityScanner } from '@objectstack/core/security';
+
+const scanner = new PluginSecurityScanner(logger);
+
+// Perform security scan
+const result = await scanner.scan({
+  pluginId: 'my-plugin',
+  version: '1.0.0',
+  files: ['src/**/*.ts'],
+  dependencies: {
+    'express': '4.18.0',
+    'lodash': '4.17.21',
+  },
+});
+
+console.log(`Security Score: ${result.score}/100`);
+console.log(`Passed: ${result.passed}`);
+console.log(`Issues:`, result.summary);
+
+// Add vulnerability to database
+scanner.addVulnerability('lodash', '4.17.20', {
+  cve: 'CVE-2021-23337',
+  severity: 'high',
+  affectedVersions: ['<=4.17.20'],
+  fixedIn: ['4.17.21'],
+});
+
+// Update vulnerability database
+await scanner.updateVulnerabilityDatabase();
+```
+
+## Integration with Kernel
+
+These components are designed to integrate with the existing ObjectKernel:
+
+```typescript
+import { 
+  ObjectKernel,
+  PluginHealthMonitor,
+  HotReloadManager,
+  DependencyResolver,
+  PluginPermissionManager,
+  PluginSandboxRuntime,
+  PluginSecurityScanner
+} from '@objectstack/core';
+
+const kernel = new ObjectKernel({ logger: { level: 'info' } });
+
+// Initialize Phase 2 components
+const healthMonitor = new PluginHealthMonitor(kernel.logger);
+const hotReload = new HotReloadManager(kernel.logger);
+const depResolver = new DependencyResolver(kernel.logger);
+const permManager = new PluginPermissionManager(kernel.logger);
+const sandbox = new PluginSandboxRuntime(kernel.logger);
+const scanner = new PluginSecurityScanner(kernel.logger);
+
+// Register plugins with enhanced features
+// ... plugin registration code ...
+
+// Bootstrap kernel
+await kernel.bootstrap();
+```
+
+## Testing
+
+Comprehensive unit tests are provided for all components:
+
+- `health-monitor.test.ts` - Health monitoring tests
+- `dependency-resolver.test.ts` - SemVer and dependency resolution tests
+- `security/permission-manager.test.ts` - Permission management tests
+
+Run tests with:
+
+```bash
+npm test
+```
+
+## Performance Considerations
+
+- Health checks run in separate intervals to avoid blocking
+- State preservation uses checksums for integrity verification
+- Dependency resolution uses efficient topological sorting
+- Resource monitoring is throttled (default 5 seconds)
+- Security scanning can be run asynchronously
+
+## Security
+
+- All permissions must be explicitly granted
+- Sandbox provides multiple isolation levels
+- Security scanner integrates with CVE databases
+- Resource limits prevent DoS attacks
+- State preservation uses checksums to detect tampering
+
+## Future Enhancements
+
+Phase 3 and beyond will add:
+- Plugin marketplace integration
+- AI-powered plugin development
+- Enhanced monitoring and observability
+- Distributed plugin management
+- Advanced security features
+
+## References
+
+- [MICROKERNEL_IMPROVEMENT_PLAN.md](../../MICROKERNEL_IMPROVEMENT_PLAN.md)
+- [ARCHITECTURE.md](../../ARCHITECTURE.md)
+- [Protocol Definitions](../spec/src/system/)

package/README.md

@@ -13,6 +13,19 @@ This package defines the fundamental runtime mechanics of the ObjectStack archit
 
 It is completely agnostic of "Data", "HTTP", or "Apps". It only knows `Plugin` and `Service`.
 
+## 🤖 AI Development Context
+
+**Role**: Microkernel / Runtime Orchestrator
+**Usage**:
+- Use `ObjectKernel` to bootstrap the application.
+- Implement `Plugin` interface to add functionality (not business logic directly).
+- Use `PluginLoader` features for dependency injection.
+
+**Architectural Interaction**:
+- `Kernel` loads `Plugins`.
+- `Plugins` register `Services`.
+- `Services` implement logic defined in `spec`.
+
 ## Features
 
 ### Core Features
@@ -254,15 +267,15 @@ kernel.use(apiPlugin);
 await kernel.bootstrap();
 ```
 
-## Enhanced Kernel Usage
+## Advanced Kernel Usage
 
-For production applications, use `EnhancedObjectKernel` for advanced features:
+For production applications, use `ObjectKernel` (formerly `EnhancedObjectKernel`) for advanced features:
 
 ```typescript
-import { EnhancedObjectKernel, PluginMetadata, ServiceLifecycle } from '@objectstack/core';
+import { ObjectKernel, PluginMetadata, ServiceLifecycle } from '@objectstack/core';
 
-// Create enhanced kernel
-const kernel = new EnhancedObjectKernel({
+// Create kernel with advanced configuration
+const kernel = new ObjectKernel({
   logger: { level: 'info', format: 'pretty' },
   defaultStartupTimeout: 30000,   // 30 seconds
   gracefulShutdown: true,
@@ -338,15 +351,15 @@ Automatic sensitive data redaction:
 
 ## API Reference
 
-### ObjectKernel (Basic)
-- `ObjectKernel` - Basic microkernel class
+### LiteKernel (Minimal)
+- `LiteKernel` - Lightweight microkernel for serverless/test
 - `createLogger(config)` - Create standalone logger
 - `Plugin` - Plugin interface
 - `PluginContext` - Runtime context for plugins
 - `Logger` - Logger interface
 
-### EnhancedObjectKernel (Advanced)
-- `EnhancedObjectKernel` - Enhanced microkernel with production features
+### ObjectKernel (Production)
+- `ObjectKernel` - Full-featured enterprise microkernel
 - `PluginLoader` - Plugin loading and validation
 - `ServiceLifecycle` - Service lifecycle management (SINGLETON, TRANSIENT, SCOPED)
 - `PluginMetadata` - Extended plugin interface with metadata
@@ -356,8 +369,8 @@ See [TypeScript definitions](./src/types.ts) for complete API.
 
 ## Documentation
 
-- [ENHANCED_FEATURES.md](./ENHANCED_FEATURES.md) - Comprehensive guide to enhanced features
-- [examples/enhanced-kernel-example.ts](./examples/enhanced-kernel-example.ts) - Complete working example
+- [ADVANCED_FEATURES.md](./ADVANCED_FEATURES.md) - Comprehensive guide to kernel features
+- [examples/kernel-features-example.ts](./examples/kernel-features-example.ts) - Complete working example
 
 ## License
 

package/REFACTORING_SUMMARY.md

@@ -0,0 +1,40 @@
+# Kernel Refactoring Summary
+
+This document summarizes the critical architectural improvements made to the `packages/core` module to address stability, performance, and correctness issues.
+
+## 1. Dependency Injection Context Fix
+**Problem:** Service factories were receiving an empty object `{}` instead of the real `PluginContext`.
+**Fix:**
+- Updated `PluginLoader.createServiceInstance` to ensure `this.context` is passed to factories.
+- Added `PluginLoader.setContext` method to inject the context from the Kernel.
+- Kernel now properly injects itself and the loader into the context before initialization.
+
+## 2. Sync/Async Gap (Service Availability)
+**Problem:** Services created asynchronously (via `awaitFactory`) were not accessible synchronously immediately after initialization, breaking code that expected `getService` to return an instance if the plugin was loaded.
+**Fix:**
+- Implemented L2 caching via `PluginLoader.getServiceInstance<T>(name: string)`.
+- Kernel's `getService` now checks this synchronous cache first before falling back to the async path.
+- Ensured singleton instances are stored in `serviceInstances` immediately upon creation.
+
+## 3. Runtime Circular Dependency Detection
+**Problem:** Complex service graphs could deadlock or crash the stack if factories recursively requested each other. Static analysis was insufficient for dynamic factories.
+**Fix:**
+- Added a `creating` Set to `PluginLoader`.
+- `createServiceInstance` now tracks which services are currently being built.
+- Throws a descriptive error if a loop is detected (e.g., `Circular dependency detected: serviceA -> serviceB -> serviceA`).
+
+## 4. Enhanced Error Handling
+**Problem:** The Kernel swallowed errors from service factories (like database connection failures) and threw a generic "Service not found" error, making debugging impossible.
+**Fix:**
+- Refined `Kernel.getService` to distinguish between "service registration missing" and "factory execution failed".
+- Factory errors are now re-thrown with their original stack trace and message.
+
+## 5. Configuration Validation
+**Problem:** Configuration validation was a scaffold without implementation.
+**Fix:**
+- Integrated `PluginConfigValidator` (Zod-based) into `PluginLoader`.
+- `validatePluginConfig` now performs actual schema validation against `plugin.configSchema`.
+
+## Verification
+- **Build:** Clean build of `dist` artifacts.
+- **Tests:** 100% Pass rate (380/380 tests) across 22 test suites.