Upgrade @objectstack/spec to v0.4.1 and migrate to System protocol namespace

docs/SPEC_REFACTORING.md

@@ -2,7 +2,10 @@
 
 ## Overview
 
-This document describes the refactoring of ObjectOS to align with the [@objectstack/spec](https://github.com/objectstack-ai/spec) protocol version 0.3.3.
+This document describes the alignment of ObjectOS with the [@objectstack/spec](https://github.com/objectstack-ai/spec) protocol.
+
+**Current Version:** v0.4.1 (Updated: 2026-01-27)  
+**Previous Version:** v0.3.3
 
 ## What is @objectstack/spec?
 
@@ -24,31 +27,34 @@ The specification is organized into five namespaces:
 - `Query` (AST), `Driver` (Interface), `Datasource`
 - `Permission`, `Sharing`, `Flow`
 
-### 2. Kernel Protocol (`@objectstack/spec/kernel`)
-*Plugin System & Runtime*
-- `Manifest` - Plugin configuration
+### 2. System Protocol (`@objectstack/spec/system`) 
+*Plugin System, Runtime Infrastructure & Security*
+- `Manifest` - Plugin configuration with contribution points
 - `Plugin` - Lifecycle hooks (onInstall, onEnable, onDisable, onUninstall)
-- `Context` - Runtime context available to plugins
+- `Context` - Runtime context available to plugins (KernelContext, PluginContextData)
 - `Logger` - Structured logging
-
-### 3. System Protocol (`@objectstack/spec/system`)
-*Runtime Infrastructure & Security*
 - `Audit` - Audit logging and event tracking
 - `Events` - Event bus and handlers
 - `Job` - Scheduled jobs and background tasks
-- `Translation` - I18n support
 
-### 4. UI Protocol (`@objectstack/spec/ui`)
+**Note:** In v0.4.1, the Kernel Protocol was merged into the System Protocol for better organization.
+
+### 3. UI Protocol (`@objectstack/spec/ui`)
 *Presentation & Interaction*
 - `App`, `Page`, `View` (Grid/Kanban)
 - `Dashboard` (Widgets), `Report`
 - `Action` (Triggers)
 
-### 5. API Protocol (`@objectstack/spec/api`)
+### 4. API Protocol (`@objectstack/spec/api`)
 *Connectivity & Contracts*
 - `Contract` (DTOs), `Endpoint` (Gateway)
 - `Discovery` (Metadata), `Realtime` (Socket)
 
+### 5. Auth Protocol (`@objectstack/spec/auth`)
+*Authentication & Authorization*
+- `User`, `Session`, `Role`
+- `Permission`, `Token`
+
 ## Changes Made
 
 ### 1. Dependencies
@@ -74,7 +80,7 @@ export type {
     PluginDefinition,
     PluginContextData,
     ObjectStackManifest,
-} from '@objectstack/spec/kernel';
+} from '@objectstack/spec/system';
 
 export type {
     ServiceObject,
@@ -159,7 +165,7 @@ export const MyPlugin: ObjectQLPlugin = {
 
 **New Style (ObjectStack Spec Plugin):**
 ```typescript
-import type { PluginDefinition, PluginContextData } from '@objectstack/spec/kernel';
+import type { PluginDefinition, PluginContextData } from '@objectstack/spec/system';
 
 export const MyPlugin: PluginDefinition = {
     async onEnable(context: PluginContextData) {
@@ -181,7 +187,7 @@ The API remains mostly unchanged. The main difference is better type safety:
 
 ```typescript
 import { ObjectOS } from '@objectos/kernel';
-import type { ObjectStackManifest } from '@objectstack/spec/kernel';
+import type { ObjectStackManifest } from '@objectstack/spec/system';
 
 const os = new ObjectOS({
     plugins: [MyPlugin],

package.json

@@ -45,7 +45,7 @@
     "@objectql/platform-node": "^3.0.1",
     "@objectql/starter-basic": "^1.8.4",
     "@objectql/starter-enterprise": "^1.8.4",
-    "@objectstack/spec": "0.3.3",
+    "@objectstack/spec": "0.4.1",
     "build": "^0.1.4"
   }
 }

packages/kernel/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @objectos/kernel
 
+## 0.2.1 (2026-01-27)
+
+### Minor Changes
+
+- **Protocol Upgrade**: Upgraded to @objectstack/spec v0.4.1
+  - Updated all imports from `@objectstack/spec/kernel` to `@objectstack/spec/system`
+  - Plugin manifest schema updated to use `objects` glob patterns instead of inline `definitions`
+  - Added support for `contributes` section for extension points (actions, events, field types, etc.)
+  - Improved namespace organization following the new protocol structure
+
+### Breaking Changes
+
+- **Manifest Schema**: The plugin manifest structure has changed in v0.4.1
+  - `definitions.objects` is no longer supported
+  - Use `objects: ['./objects/*.object.yml']` glob patterns to reference object files
+  - Use `contributes` section to register actions, events, and other extension points
+
+### Migration Guide
+
+If you have existing plugins, update your manifest from:
+
+```typescript
+// Old (v0.3.3)
+const manifest = {
+  id: 'com.example.plugin',
+  version: '1.0.0',
+  type: 'plugin',
+  name: 'My Plugin',
+  definitions: {
+    objects: {
+      my_object: { /* inline definition */ }
+    }
+  }
+};
+```
+
+To:
+
+```typescript
+// New (v0.4.1)
+const manifest = {
+  id: 'com.example.plugin',
+  version: '1.0.0',
+  type: 'plugin',
+  name: 'My Plugin',
+  objects: ['./objects/*.object.yml'], // Reference files with glob patterns
+  contributes: {
+    actions: [{ name: 'myAction', label: 'My Action' }],
+    events: ['my_object.created']
+  }
+};
+```
+
 ## 0.2.0 (2026-01-17)
 
 ### Minor Changes

packages/kernel/README.md

@@ -6,7 +6,7 @@ The core runtime engine for ObjectOS - a metadata-driven platform built on the [
 
 `@objectos/kernel` is the execution engine that powers ObjectOS. It extends ObjectQL with application-specific capabilities, providing:
 
-- **Spec-Compliant Types**: Built on `@objectstack/spec` for protocol consistency
+- **Spec-Compliant Types**: Built on `@objectstack/spec` v0.4.1 for protocol consistency
 - **Metadata Processing**: Parse and validate object definitions, apps, and data files
 - **Plugin Lifecycle**: Standardized hooks (onInstall, onEnable, onDisable, onUninstall)
 - **Permission Enforcement**: Apply role-based access control and field-level security
@@ -15,11 +15,11 @@ The core runtime engine for ObjectOS - a metadata-driven platform built on the [
 
 ## Protocol Compliance
 
-This package implements the **@objectstack/spec** protocol:
+This package implements the **@objectstack/spec v0.4.1** protocol:
 
-- **Kernel Protocol** (`@objectstack/spec/kernel`): Plugin lifecycle, manifests, context
+- **System Protocol** (`@objectstack/spec/system`): Plugin lifecycle, manifests, context, kernel infrastructure
 - **Data Protocol** (`@objectstack/spec/data`): Object schemas, fields, queries
-- **System Protocol** (`@objectstack/spec/system`): Audit, events, jobs
+- **API Protocol** (`@objectstack/spec/api`): REST/GraphQL contracts, endpoints, discovery
 
 All TypeScript types are imported from the spec to ensure consistency across the ecosystem.
 
@@ -28,7 +28,7 @@ import type {
   PluginDefinition,
   PluginContextData,
   ObjectStackManifest 
-} from '@objectstack/spec/kernel';
+} from '@objectstack/spec/system';
 
 import type { 
   ServiceObject,

packages/kernel/package.json

@@ -11,7 +11,7 @@
   "dependencies": {
     "@objectql/core": "^3.0.1",
     "@objectql/types": "^3.0.1",
-    "@objectstack/spec": "0.3.3",
+    "@objectstack/spec": "0.4.1",
     "fast-glob": "^3.3.2",
     "js-yaml": "^4.1.0"
   },

packages/kernel/src/examples/crm-plugin-example.ts

@@ -3,7 +3,7 @@
  */
 
 import { ObjectOS } from '../objectos';
-import type { ObjectStackManifest, PluginDefinition } from '@objectstack/spec/kernel';
+import type { ObjectStackManifest, PluginDefinition } from '@objectstack/spec/system';
 
 export const CRMManifest: ObjectStackManifest = {
     id: 'com.example.crm',
@@ -12,37 +12,21 @@ export const CRMManifest: ObjectStackManifest = {
     name: 'Example CRM Plugin',
     description: 'A complete CRM plugin demonstrating spec compliance',
     permissions: ['system.user.read', 'system.data.write'],
-    definitions: {
-        objects: {
-            crm_lead: {
-                name: 'crm_lead',
-                label: 'Lead',
-                pluralLabel: 'Leads',
-                description: 'Sales lead tracking',
-                icon: 'user-plus',
-                active: true,
-                isSystem: false,
-                abstract: false,
-                datasource: 'default',
-                fields: {
-                    name: {
-                        type: 'text',
-                        label: 'Lead Name',
-                        required: true,
-                        searchable: true,
-                        multiple: false,
-                        unique: false,
-                        deleteBehavior: 'set_null',
-                        hidden: false,
-                        readonly: false,
-                        encryption: false,
-                        index: false,
-                        externalId: false,
-                    },
-                },
-            },
-        },
-    },
+    // In v0.4.1, objects are defined via glob patterns pointing to object definition files
+    objects: ['./objects/*.object.yml'],
+    // Contribution points for extending the platform
+    contributes: {
+        // Register custom actions that can be invoked by flows or API
+        actions: [
+            {
+                name: 'convertLead',
+                label: 'Convert Lead to Account',
+                description: 'Converts a lead to an account and contact',
+            }
+        ],
+        // Register custom events that this plugin listens to
+        events: ['lead.created', 'lead.converted'],
+    }
 };
 
 export const CRMPlugin: PluginDefinition = {

packages/kernel/src/kernel-context.ts

@@ -1,11 +1,11 @@
 /**
  * Kernel Context Implementation
  * 
- * Implements the KernelContext interface from @objectstack/spec/kernel.
+ * Implements the KernelContext interface from @objectstack/spec/system.
  * Provides static environment information available at boot time.
  */
 
-import type { KernelContext } from '@objectstack/spec/kernel';
+import type { KernelContext } from '@objectstack/spec/system';
 import { randomUUID } from 'crypto';
 
 /**

packages/kernel/src/logger.ts

@@ -1,7 +1,7 @@
 /**
  * Logger Implementation
  * 
- * Provides structured logging that conforms to the @objectstack/spec/kernel Logger interface.
+ * Provides structured logging that conforms to the @objectstack/spec/system Logger interface.
  */
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';

packages/kernel/src/objectos.ts

@@ -1,6 +1,6 @@
 import { ObjectQL } from '@objectql/core';
 import { ObjectQLConfig, ObjectQLPlugin } from '@objectql/types';
-import type { PluginDefinition, ObjectStackManifest, KernelContext } from '@objectstack/spec/kernel';
+import type { PluginDefinition, ObjectStackManifest, KernelContext } from '@objectstack/spec/system';
 import { ObjectOSPlugin } from './plugins/objectql';
 import { KernelContextManager } from './kernel-context';
 import { StorageManager } from './scoped-storage';

packages/kernel/src/plugin-context.ts

@@ -2,10 +2,10 @@
  * Plugin Context Builder
  * 
  * Creates PluginContext instances that provide plugins with access to
- * ObjectStack APIs according to @objectstack/spec/kernel.
+ * ObjectStack APIs according to @objectstack/spec/system.
  */
 
-import type { PluginContextData } from '@objectstack/spec/kernel';
+import type { PluginContextData } from '@objectstack/spec/system';
 import type { IObjectQL } from '@objectql/types';
 import { Logger, createLogger } from './logger';
 import { ScopedStorage } from './scoped-storage';

packages/kernel/src/plugin-manager.ts

@@ -1,15 +1,15 @@
 /**
  * Plugin Manager
  * 
- * Manages the plugin lifecycle according to @objectstack/spec/kernel.
+ * Manages the plugin lifecycle according to @objectstack/spec/system.
  * Handles plugin registration, initialization, and lifecycle hooks.
  */
 
 import type { 
     PluginDefinition, 
     PluginContextData, 
     ObjectStackManifest 
-} from '@objectstack/spec/kernel';
+} from '@objectstack/spec/system';
 import { Logger, createLogger } from './logger';
 import { ScopedStorage } from './scoped-storage';