refactor(spec): retire 'ObjectOS' from the spec's public surface — Kernel naming

.changeset/retire-objectos-spec-identifiers.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": minor
+---
+
+Retire the "ObjectOS" layer name from the spec's public surface — the control layer is the **Kernel**; ObjectOS now exclusively names the commercial runtime environment.
+
+Renames (deprecated aliases kept for one release, so existing imports keep compiling):
+
+- `ObjectOSCapabilitiesSchema` → `KernelCapabilitiesSchema`
+- `ObjectOSCapabilities` (type) → `KernelCapabilities`
+- `ObjectOSKernel` (interface) → `IKernel` (`PluginContext.os` is now typed as `IKernel`)
+
+Migration: replace the old names with the new ones — a find/replace of the three identifiers above is sufficient; runtime behavior, schema shapes, and JSON output are unchanged. TSDoc and generated reference docs now say "the ObjectStack runtime" / "Kernel" instead of "ObjectOS" (product mentions like ObjectOS Cloud in the Cloud protocol domain are unchanged).

content/docs/references/system/environment-artifact.mdx

@@ -9,7 +9,7 @@ description: Environment Artifact protocol schemas
 
 Defines the immutable envelope produced by `objectstack compile` and consumed
 
-by ObjectOS at boot. The artifact carries everything an ObjectOS instance
+by the ObjectStack runtime at boot. The artifact carries everything a runtime instance
 
 needs to hydrate an environment kernel without reading control-plane DB rows
 

packages/spec/api-surface.json

@@ -44,6 +44,8 @@
     "ExpressionSchema (const)",
     "F (const)",
     "GUEST_POSITION (const)",
+    "KernelCapabilities (type)",
+    "KernelCapabilitiesSchema (const)",
     "MAP_SUPPORTED_FIELDS (const)",
     "METADATA_ALIASES (const)",
     "MIGRATIONS_BY_MAJOR (const)",
@@ -799,6 +801,7 @@
     "HttpServerConfig (type)",
     "HttpServerConfigInput (type)",
     "HttpServerConfigSchema (const)",
+    "IKernel (interface)",
     "ISettingsCapability (interface)",
     "ISettingsClient (interface)",
     "InAppNotification (type)",

packages/spec/src/api/protocol.test.ts

@@ -355,7 +355,7 @@ describe('GetDiscoveryResponseSchema (capabilities)', () => {
 
   it('should accept full DiscoverySchema-compatible response', () => {
     const result = GetDiscoveryResponseSchema.safeParse({
-      name: 'ObjectOS',
+      name: 'ObjectStack',
       version: '1.0.0',
       environment: 'development',
       routes: { data: '/api/v1/data', metadata: '/api/v1/meta' },
@@ -366,7 +366,7 @@ describe('GetDiscoveryResponseSchema (capabilities)', () => {
     });
     expect(result.success).toBe(true);
     if (result.success) {
-      expect(result.data.name).toBe('ObjectOS');
+      expect(result.data.name).toBe('ObjectStack');
       expect(result.data.environment).toBe('development');
     }
   });

packages/spec/src/index.ts

@@ -63,6 +63,7 @@ export {
   ObjectStackCapabilitiesSchema,
   ObjectQLCapabilitiesSchema,
   ObjectUICapabilitiesSchema,
+  KernelCapabilitiesSchema,
   ObjectOSCapabilitiesSchema
 } from './stack.zod';
 

packages/spec/src/stack.test.ts

@@ -2,13 +2,13 @@ import { describe, it, expect } from 'vitest';
 import {
   ObjectQLCapabilitiesSchema,
   ObjectUICapabilitiesSchema,
-  ObjectOSCapabilitiesSchema,
+  KernelCapabilitiesSchema,
   ObjectStackCapabilitiesSchema,
   ObjectStackDefinitionSchema,
   defineStack,
   type ObjectQLCapabilities,
   type ObjectUICapabilities,
-  type ObjectOSCapabilities,
+  type KernelCapabilities,
   type ObjectStackCapabilities,
   type ObjectStackDefinitionInput,
 } from './stack.zod';
@@ -148,9 +148,14 @@ describe('ObjectUICapabilitiesSchema', () => {
   });
 });
 
-describe('ObjectOSCapabilitiesSchema', () => {
-  it('should accept valid ObjectOS capabilities with all features enabled', () => {
-    const capabilities: ObjectOSCapabilities = {
+describe('KernelCapabilitiesSchema', () => {
+  it('keeps the deprecated ObjectOS aliases pointing at the renamed exports', async () => {
+    const mod = await import('./stack.zod');
+    expect(mod.ObjectOSCapabilitiesSchema).toBe(mod.KernelCapabilitiesSchema);
+  });
+
+  it('should accept valid kernel capabilities with all features enabled', () => {
+    const capabilities: KernelCapabilities = {
       version: '1.0.0',
       environment: 'production',
       restApi: true,
@@ -183,20 +188,20 @@ describe('ObjectOSCapabilitiesSchema', () => {
       },
     };
 
-    expect(() => ObjectOSCapabilitiesSchema.parse(capabilities)).not.toThrow();
+    expect(() => KernelCapabilitiesSchema.parse(capabilities)).not.toThrow();
   });
 
   it('should require version and environment fields', () => {
-    expect(() => ObjectOSCapabilitiesSchema.parse({})).toThrow();
+    expect(() => KernelCapabilitiesSchema.parse({})).toThrow();
 
     expect(() =>
-      ObjectOSCapabilitiesSchema.parse({
+      KernelCapabilitiesSchema.parse({
         version: '1.0.0',
       })
     ).toThrow();
 
     expect(() =>
-      ObjectOSCapabilitiesSchema.parse({
+      KernelCapabilitiesSchema.parse({
         version: '1.0.0',
         environment: 'development',
       })
@@ -205,7 +210,7 @@ describe('ObjectOSCapabilitiesSchema', () => {
 
   it('should validate environment enum values', () => {
     expect(() =>
-      ObjectOSCapabilitiesSchema.parse({
+      KernelCapabilitiesSchema.parse({
         version: '1.0.0',
         environment: 'invalid',
       })
@@ -214,7 +219,7 @@ describe('ObjectOSCapabilitiesSchema', () => {
     const validEnvironments = ['development', 'test', 'staging', 'production'];
     validEnvironments.forEach((env) => {
       expect(() =>
-        ObjectOSCapabilitiesSchema.parse({
+        KernelCapabilitiesSchema.parse({
           version: '1.0.0',
           environment: env,
         })
@@ -223,7 +228,7 @@ describe('ObjectOSCapabilitiesSchema', () => {
   });
 
   it('should use default values for boolean fields', () => {
-    const result = ObjectOSCapabilitiesSchema.parse({
+    const result = KernelCapabilitiesSchema.parse({
       version: '1.0.0',
       environment: 'development',
     });
@@ -236,7 +241,7 @@ describe('ObjectOSCapabilitiesSchema', () => {
   });
 
   it('should accept optional limits object', () => {
-    const withLimits = ObjectOSCapabilitiesSchema.parse({
+    const withLimits = KernelCapabilitiesSchema.parse({
       version: '1.0.0',
       environment: 'production',
       limits: {
@@ -248,7 +253,7 @@ describe('ObjectOSCapabilitiesSchema', () => {
     expect(withLimits.limits?.maxObjects).toBe(500);
     expect(withLimits.limits?.apiRateLimit).toBe(100);
 
-    const withoutLimits = ObjectOSCapabilitiesSchema.parse({
+    const withoutLimits = KernelCapabilitiesSchema.parse({
       version: '1.0.0',
       environment: 'development',
     });

packages/spec/src/stack.zod.ts

@@ -1229,16 +1229,16 @@ export function composeStacks(
 /**
  * 2. RUNTIME CAPABILITIES PROTOCOL (Dynamic)
  * ----------------------------------------------------------------------
- * Describes what the ObjectOS Platform *is* and *can do*.
+ * Describes what the ObjectStack platform *is* and *can do*.
  * AI Agents read this to understand:
  * - What APIs are available?
  * - What features are enabled?
  * - What limits exist?
- * 
+ *
  * The capabilities are organized by subsystem for clarity:
  * - ObjectQL: Data Layer capabilities
- * - ObjectUI: User Interface Layer capabilities  
- * - ObjectOS: System Layer capabilities
+ * - ObjectUI: User Interface Layer capabilities
+ * - Kernel: System Layer capabilities
  */
 
 /**
@@ -1322,17 +1322,17 @@ export const ObjectUICapabilitiesSchema = lazySchema(() => z.object({
 }));
 
 /**
- * ObjectOS Capabilities Schema
- * 
+ * Kernel Capabilities Schema
+ *
  * Defines capabilities related to the System Layer:
  * - Runtime environment and platform features
  * - API and integration capabilities
  * - Security and multi-tenancy
  * - System services (events, jobs, audit)
  */
-export const ObjectOSCapabilitiesSchema = lazySchema(() => z.object({
+export const KernelCapabilitiesSchema = lazySchema(() => z.object({
   /** System Identity */
-  version: z.string().describe('ObjectOS Kernel Version'),
+  version: z.string().describe('Kernel version'),
   environment: z.enum(['development', 'test', 'staging', 'production']),
 
   /** API Surface */
@@ -1424,14 +1424,19 @@ export const ObjectStackCapabilitiesSchema = lazySchema(() => z.object({
   /** User Interface Layer Capabilities (ObjectUI) */
   ui: ObjectUICapabilitiesSchema.describe('UI Layer capabilities'),
 
-  /** System/Runtime Layer Capabilities (ObjectOS) */
-  system: ObjectOSCapabilitiesSchema.describe('System/Runtime Layer capabilities'),
+  /** System/Runtime Layer Capabilities (Kernel) */
+  system: KernelCapabilitiesSchema.describe('System/Runtime Layer capabilities'),
 }));
 
 export type ObjectQLCapabilities = z.infer<typeof ObjectQLCapabilitiesSchema>;
 export type ObjectUICapabilities = z.infer<typeof ObjectUICapabilitiesSchema>;
-export type ObjectOSCapabilities = z.infer<typeof ObjectOSCapabilitiesSchema>;
+export type KernelCapabilities = z.infer<typeof KernelCapabilitiesSchema>;
 export type ObjectStackCapabilities = z.infer<typeof ObjectStackCapabilitiesSchema>;
 
+/** @deprecated Renamed — use {@link KernelCapabilitiesSchema}. The "ObjectOS" layer name is retired; ObjectOS now names the commercial runtime environment. */
+export const ObjectOSCapabilitiesSchema = KernelCapabilitiesSchema;
+/** @deprecated Renamed — use {@link KernelCapabilities}. */
+export type ObjectOSCapabilities = KernelCapabilities;
+
 
 

packages/spec/src/system/constants/index.ts

@@ -4,7 +4,7 @@
  * ObjectStack Convention Constants
  * 
  * This package defines the "Law of Location" - where things must be in ObjectStack packages.
- * These paths are used by ObjectOS Runtime, ObjectStack CLI, and ObjectStudio IDE.
+ * These paths are used by the ObjectStack runtime, CLI, and Studio IDE.
  * 
  * Guiding Principle: "Strict Types, No Logic"
  * This package has NO database connections, NO UI components, and NO runtime business logic.

packages/spec/src/system/constants/paths.ts

@@ -5,7 +5,7 @@
  * These define the "Law of Location" - where things must be in ObjectStack packages.
  * 
  * These paths are the source of truth used by:
- * - ObjectOS Runtime (to locate package components)
+ * - the ObjectStack runtime (to locate package components)
  * - ObjectStack CLI (to scaffold and validate packages)
  * - ObjectStudio IDE (to provide intelligent navigation and validation)
  */

packages/spec/src/system/environment-artifact.zod.ts

@@ -6,7 +6,7 @@ import { z } from 'zod';
  * # Environment Artifact Format Protocol (v0)
  *
  * Defines the immutable envelope produced by `objectstack compile` and consumed
- * by ObjectOS at boot. The artifact carries everything an ObjectOS instance
+ * by the ObjectStack runtime at boot. The artifact carries everything a runtime instance
  * needs to hydrate an environment kernel without reading control-plane DB rows
  * directly.
  *
@@ -49,7 +49,7 @@ export type EnvironmentArtifactHashAlgorithm = z.infer<typeof EnvironmentArtifac
 
 /**
  * Content-addressable checksum of the canonical JSON-serialized artifact body
- * (everything except the `checksum` field itself). Used by ObjectOS to verify
+ * (everything except the `checksum` field itself). Used by the runtime to verify
  * that the artifact bytes were not tampered with in transit and to key the
  * local artifact cache.
  */
@@ -126,7 +126,7 @@ export type EnvironmentArtifactFunction = z.infer<typeof EnvironmentArtifactFunc
 // ==========================================
 
 /**
- * Plugin/driver requirement entry. ObjectOS uses these to verify that the
+ * Plugin/driver requirement entry. The runtime uses these to verify that the
  * runtime has every plugin the environment depends on before hydrating the kernel.
  * Configuration values live in **Deployment Config**, not in the artifact.
  */
@@ -180,7 +180,7 @@ export type EnvironmentArtifactManifest = z.infer<typeof EnvironmentArtifactMani
  * artifact envelope to every domain schema bump.
  *
  * Treat this as a typed bag of arrays keyed by metadata category. Unknown
- * categories are passed through (`passthrough()`) so older ObjectOS builds can
+ * categories are passed through (`passthrough()`) so older runtime builds can
  * boot newer artifacts safely if no breaking changes were made.
  */
 export const EnvironmentArtifactMetadataSchema = z
@@ -247,7 +247,7 @@ export type EnvironmentArtifactPayloadRef = z.infer<typeof EnvironmentArtifactPa
  *
  * Produced by `objectstack compile`, served by the Environment Artifact API
  * (`GET /api/v1/cloud/environments/:environmentId/artifact`), and consumed by the
- * ObjectOS metadata loader to hydrate an environment kernel.
+ * runtime metadata loader to hydrate an environment kernel.
  *
  * Required fields (v0):
  * - `schemaVersion`: tracks the envelope itself.
@@ -274,7 +274,7 @@ export const EnvironmentArtifactSchema = z
 
     /**
      * Monotonic, content-addressable revision id assigned by the control plane
-     * when the artifact is published. Used as a cache key by ObjectOS and as
+     * when the artifact is published. Used as a cache key by the runtime and as
      * the rollback target by Studio.
      */
     commitId: z.string().min(1).describe('Content-addressable revision id'),

packages/spec/src/system/types/index.ts

@@ -3,7 +3,7 @@
 /**
  * ObjectStack Plugin Runtime Interfaces
  * 
- * This package defines the contract that every plugin must implement to be loaded by ObjectOS.
+ * This package defines the contract that every plugin must implement to be loaded by the ObjectStack runtime.
  */
 
 export * from './plugin';

packages/spec/src/system/types/plugin.ts

@@ -2,7 +2,7 @@
 
 /**
  * Runtime interfaces for ObjectStack plugins.
- * These define the contract that every plugin must implement to be loaded by ObjectOS.
+ * These define the contract that every plugin must implement to be loaded by the ObjectStack runtime.
  */
 
 /**
@@ -42,10 +42,10 @@ export interface ObjectQLClient {
 }
 
 /**
- * ObjectOS Kernel interface.
+ * Kernel interface.
  * Provides access to core operating system services.
  */
-export interface ObjectOSKernel {
+export interface IKernel {
   /**
    * Get a reference to another installed plugin by its ID.
    * @param pluginId - The unique identifier of the plugin
@@ -69,6 +69,10 @@ export interface ObjectOSKernel {
   on(event: string, handler: (data: any) => void): () => void;
 }
 
+/** @deprecated Renamed — use {@link IKernel}. The "ObjectOS" layer name is retired; ObjectOS now names the commercial runtime environment. Kept as an empty interface extension (not a type alias) so declaration merging and the published API surface stay interface-compatible. */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ObjectOSKernel extends IKernel {}
+
 /**
  * Plugin Context provided to plugin lifecycle methods.
  * This context gives plugins access to the ObjectStack runtime environment.
@@ -81,10 +85,10 @@ export interface PluginContext {
   ql: ObjectQLClient;
 
   /**
-   * ObjectOS kernel for system-level operations.
+   * Kernel for system-level operations.
    * Use this to interact with other plugins and system services.
    */
-  os: ObjectOSKernel;
+  os: IKernel;
 
   /**
    * Logger instance for structured logging.