From 6715d675293c071c56cf5180495bd8b263ede400 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 15 Jul 2026 13:30:16 +0000
Subject: [PATCH 1/2] =?UTF-8?q?refactor(spec):=20retire=20'ObjectOS'=20fro?=
 =?UTF-8?q?m=20the=20spec's=20public=20surface=20=E2=80=94=20Kernel=20nami?=
 =?UTF-8?q?ng?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Completes the layer-name retirement (#2955) inside packages/spec:

- Public API renames with deprecated aliases (kept one release):
  ObjectOSCapabilitiesSchema → KernelCapabilitiesSchema,
  ObjectOSCapabilities → KernelCapabilities,
  ObjectOSKernel → IKernel (PluginContext.os now typed IKernel).
  Alias identity is regression-tested.
- TSDoc/comments: layer-actor wording now 'the ObjectStack runtime' /
  'Kernel' (plugin contract, constants, environment-artifact). Product
  usages in the Cloud domain (ObjectOS Cloud, 'Register → Instant
  ObjectOS', app-store) are deliberately unchanged.
- Test fixtures: discovery-response name fixture 'ObjectOS' → 'ObjectStack'.
- references/: regenerated; only system/environment-artifact.mdx is from
  this change. The regen also surfaced 7 files of pre-existing drift
  (ADR-0091/0095 era) which are deliberately NOT included here — that
  drift belongs to the changes that caused it.
- Changeset: minor, with FROM → TO migration notes.

Verified: spec tsc --noEmit clean; vitest stack.test + api/protocol.test
113/113 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0162o68e5w3bpUBEVRQboUGG
---
 .../retire-objectos-spec-identifiers.md       | 13 ++++++++
 .../system/environment-artifact.mdx           |  2 +-
 packages/spec/src/api/protocol.test.ts        |  4 +--
 packages/spec/src/index.ts                    |  1 +
 packages/spec/src/stack.test.ts               | 33 +++++++++++--------
 packages/spec/src/stack.zod.ts                | 27 ++++++++-------
 packages/spec/src/system/constants/index.ts   |  2 +-
 packages/spec/src/system/constants/paths.ts   |  2 +-
 .../src/system/environment-artifact.zod.ts    | 12 +++----
 packages/spec/src/system/types/index.ts       |  2 +-
 packages/spec/src/system/types/plugin.ts      | 13 +++++---
 11 files changed, 69 insertions(+), 42 deletions(-)
 create mode 100644 .changeset/retire-objectos-spec-identifiers.md

diff --git a/.changeset/retire-objectos-spec-identifiers.md b/.changeset/retire-objectos-spec-identifiers.md
new file mode 100644
index 0000000000..ba882a6d07
--- /dev/null
+++ b/.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).
diff --git a/content/docs/references/system/environment-artifact.mdx b/content/docs/references/system/environment-artifact.mdx
index 43c130b9b5..c36430ad8c 100644
--- a/content/docs/references/system/environment-artifact.mdx
+++ b/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
 
diff --git a/packages/spec/src/api/protocol.test.ts b/packages/spec/src/api/protocol.test.ts
index 62e257aecf..ed9219386e 100644
--- a/packages/spec/src/api/protocol.test.ts
+++ b/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');
     }
   });
diff --git a/packages/spec/src/index.ts b/packages/spec/src/index.ts
index 72580b9bd5..d2616f5cea 100644
--- a/packages/spec/src/index.ts
+++ b/packages/spec/src/index.ts
@@ -63,6 +63,7 @@ export {
   ObjectStackCapabilitiesSchema,
   ObjectQLCapabilitiesSchema,
   ObjectUICapabilitiesSchema,
+  KernelCapabilitiesSchema,
   ObjectOSCapabilitiesSchema
 } from './stack.zod';
 
diff --git a/packages/spec/src/stack.test.ts b/packages/spec/src/stack.test.ts
index 9a9739ab1a..0981434d40 100644
--- a/packages/spec/src/stack.test.ts
+++ b/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',
     });
diff --git a/packages/spec/src/stack.zod.ts b/packages/spec/src/stack.zod.ts
index 2c85bd9d00..288dbb5062 100644
--- a/packages/spec/src/stack.zod.ts
+++ b/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;
+
 
 
diff --git a/packages/spec/src/system/constants/index.ts b/packages/spec/src/system/constants/index.ts
index 2eef1e0d11..52812455c9 100644
--- a/packages/spec/src/system/constants/index.ts
+++ b/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.
diff --git a/packages/spec/src/system/constants/paths.ts b/packages/spec/src/system/constants/paths.ts
index 1d7e42ce68..532562911c 100644
--- a/packages/spec/src/system/constants/paths.ts
+++ b/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)
  */
diff --git a/packages/spec/src/system/environment-artifact.zod.ts b/packages/spec/src/system/environment-artifact.zod.ts
index b237e77fa5..05ef94abb7 100644
--- a/packages/spec/src/system/environment-artifact.zod.ts
+++ b/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'),
diff --git a/packages/spec/src/system/types/index.ts b/packages/spec/src/system/types/index.ts
index 36c65b4ab1..9866c3e231 100644
--- a/packages/spec/src/system/types/index.ts
+++ b/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';
diff --git a/packages/spec/src/system/types/plugin.ts b/packages/spec/src/system/types/plugin.ts
index 71cd942548..46399afd33 100644
--- a/packages/spec/src/system/types/plugin.ts
+++ b/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,9 @@ 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. */
+export type ObjectOSKernel = IKernel;
+
 /**
  * Plugin Context provided to plugin lifecycle methods.
  * This context gives plugins access to the ObjectStack runtime environment.
@@ -81,10 +84,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.

From 2fc6d1f4b11e706ecfbbfdd5336b256fc5bb2c46 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 15 Jul 2026 13:41:23 +0000
Subject: [PATCH 2/2] fix(spec): keep ObjectOSKernel as an interface extension;
 commit api-surface snapshot
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The api-surface guard flagged interface→type as a removal (breaking).
ObjectOSKernel is now '/** @deprecated */ interface ObjectOSKernel
extends IKernel {}' — declaration merging and interface identity are
preserved, so the surface records additions only:
+ KernelCapabilitiesSchema (const), + KernelCapabilities (type),
+ IKernel (interface). check:api-surface green after a full dist build.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0162o68e5w3bpUBEVRQboUGG
---
 packages/spec/api-surface.json           | 3 +++
 packages/spec/src/system/types/plugin.ts | 5 +++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/spec/api-surface.json b/packages/spec/api-surface.json
index ba7c261406..ac2bfbd461 100644
--- a/packages/spec/api-surface.json
+++ b/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)",
diff --git a/packages/spec/src/system/types/plugin.ts b/packages/spec/src/system/types/plugin.ts
index 46399afd33..b5e804739e 100644
--- a/packages/spec/src/system/types/plugin.ts
+++ b/packages/spec/src/system/types/plugin.ts
@@ -69,8 +69,9 @@ export interface IKernel {
   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. */
-export type ObjectOSKernel = IKernel;
+/** @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.