Deprecate @objectql/core per migration guide

content/docs/architecture/core.mdx

@@ -1,10 +1,15 @@
 ---
-title: "@objectql/core"
+title: "@objectql/core (Deprecated)"
 description: The Runtime Engine - Core ORM, validation, and business logic compiler for ObjectQL
 ---
 
 # @objectql/core
 
+<Callout type="warn" title="Deprecated">
+  `@objectql/core` is deprecated. All core functionality is now available in [`@objectstack/objectql`](https://www.npmjs.com/package/@objectstack/objectql).
+  See the [Migration Guide](/docs/guides/objectql-migration) for step-by-step instructions.
+</Callout>
+
 **The Runtime Engine**: The core ORM and business logic compiler for ObjectQL. This package transforms abstract metadata (defined in `@objectql/types`) into executable database operations, validations, and business rules.
 
 ## Overview

content/docs/guides/meta.json

@@ -3,6 +3,7 @@
   "pages": [
     "error-handling",
     "architecture",
-    "migration-v5"
+    "migration-v5",
+    "objectql-migration"
   ]
 }

content/docs/guides/objectql-migration.mdx

@@ -0,0 +1,139 @@
+---
+title: "Migrating from @objectql/core"
+description: "Step-by-step guide for migrating from @objectql/core to @objectstack/objectql"
+---
+
+# Migrating from `@objectql/core` to `@objectstack/objectql`
+
+All core functionality previously provided by `@objectql/core` is now available upstream in `@objectstack/objectql`. This guide walks you through migrating your project so that `@objectql/core` can be removed.
+
+## Why Migrate?
+
+| | `@objectql/core` (deprecated) | `@objectstack/objectql` (recommended) |
+| :--- | :--- | :--- |
+| **Engine** | Bridge class extending upstream `ObjectQL` | Canonical `ObjectQL` engine |
+| **Kernel Factory** | `createObjectQLKernel()` | `createObjectQLKernel()` (identical API) |
+| **Introspection** | `toTitleCase`, `convertIntrospectedSchemaToObjects` | Same functions, same signatures |
+| **Registry** | Re-exports from upstream | Direct exports |
+| **MetadataRegistry** | `@objectql/types` `MetadataRegistry` class | `MetadataFacade` (async `IMetadataService`) |
+| **Maintenance** | Planned deprecation | Actively maintained |
+
+## Step 1 — Update Dependencies
+
+```diff
+  // package.json
+  {
+    "dependencies": {
+-     "@objectql/core": "^4.x",
+-     "@objectql/types": "^4.x",
++     "@objectstack/objectql": "^3.0.4"
+    }
+  }
+```
+
+Then re-install:
+
+```bash
+pnpm install
+```
+
+## Step 2 — Update Imports
+
+### Engine, Repository & Context
+
+```diff
+- import { ObjectQL, ObjectRepository, ScopedContext } from '@objectql/core';
++ import { ObjectQL, ObjectRepository, ScopedContext } from '@objectstack/objectql';
+```
+
+```diff
+- import type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from '@objectql/core';
++ import type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from '@objectstack/objectql';
+```
+
+### Schema Registry
+
+```diff
+- import { SchemaRegistry } from '@objectql/core';
++ import { SchemaRegistry } from '@objectstack/objectql';
+```
+
+### Kernel Factory
+
+```diff
+- import { createObjectQLKernel } from '@objectql/core';
++ import { createObjectQLKernel } from '@objectstack/objectql';
+```
+
+### Utility Functions
+
+```diff
+- import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectql/core';
++ import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
+```
+
+### Introspection Types
+
+```diff
+- import type { IntrospectedSchema, IntrospectedTable } from '@objectql/types';
++ import type { IntrospectedSchema, IntrospectedTable } from '@objectstack/objectql';
+```
+
+## Step 3 — API Differences
+
+### `createObjectQLKernel()`
+
+The function signature is identical. The only change is the return type uses the upstream `ObjectKernel`:
+
+```typescript
+import { createObjectQLKernel } from '@objectstack/objectql';
+
+const kernel = await createObjectQLKernel({
+  plugins: [myDriverPlugin],
+});
+await kernel.start();
+```
+
+### MetadataRegistry → MetadataFacade
+
+If you were using `MetadataRegistry` from `@objectql/types`, the upstream equivalent is `MetadataFacade`. The key difference is that `MetadataFacade` methods are **async**:
+
+```diff
+- import { MetadataRegistry } from '@objectql/types';
+- const registry = new MetadataRegistry();
+- registry.register('object', myObject);
+- const obj = registry.get('object', 'account');
++ import { MetadataFacade } from '@objectstack/objectql';
++ const facade = new MetadataFacade();
++ await facade.register('object', 'account', myObject);
++ const obj = await facade.get('object', 'account');
+```
+
+### ObjectQLPlugin
+
+Both packages export an `ObjectQLPlugin`, but they serve different roles:
+
+| | `@objectql/core` `ObjectQLPlugin` | `@objectstack/objectql` `ObjectQLPlugin` |
+| :--- | :--- | :--- |
+| Interface | `RuntimePlugin` (from `@objectql/types`) | `Plugin` (from `@objectstack/core`) |
+| Role | Orchestrator composing sub-plugins (validator, formula, query) | Kernel plugin registering ObjectQL as core services |
+
+If you were using the `@objectql/core` `ObjectQLPlugin` to compose sub-plugins (`ValidatorPlugin`, `FormulaPlugin`, `QueryPlugin`), those downstream plugins are **not** part of this migration — they remain in the `@objectql` ecosystem.
+
+## Step 4 — Remove `@objectql/core`
+
+Once all imports are updated and tests pass:
+
+```bash
+pnpm remove @objectql/core @objectql/types
+```
+
+## Checklist
+
+- [ ] Replace `@objectql/core` dependency with `@objectstack/objectql` in `package.json`
+- [ ] Update all `import` statements (engine, registry, kernel factory, utilities, types)
+- [ ] Replace `MetadataRegistry` usage with `MetadataFacade` (add `await`)
+- [ ] Verify `ObjectQLPlugin` usage matches the upstream interface
+- [ ] Run `pnpm build` and fix any remaining type errors
+- [ ] Run `pnpm test` to verify behavior
+- [ ] Remove `@objectql/core` and `@objectql/types` from dependencies

examples/showcase/enterprise-erp/src/plugins/audit/audit.plugin.ts

@@ -6,8 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// Import ObjectQLPlugin types from @objectql/core instead of @objectstack/runtime
-// to avoid ESM/CJS compatibility issues
+// Plugin types defined locally to avoid ESM/CJS compatibility issues
 type RuntimeContext = any;
 
 interface ObjectQLPlugin {

packages/foundation/core/README.md

@@ -1,8 +1,11 @@
 # @objectql/core
 
-> **Implementation Status**: ✅ **Production Ready** - All core features fully implemented and tested. See [Implementation Status](https://github.com/objectstack-ai/objectql/blob/main/IMPLEMENTATION_STATUS.md) for complete details.
+> ⚠️ **DEPRECATED**: This package is deprecated. Use [`@objectstack/objectql`](https://www.npmjs.com/package/@objectstack/objectql) instead.
+> See the [Migration Guide](https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx) for step-by-step instructions.
 
-The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, transaction management, and **metadata-driven validation**. As of version 4.0.0, it wraps the **ObjectKernel** for plugin architecture and lifecycle management.
+The core ORM and runtime engine for ObjectQL. All core functionality (ObjectQL engine, SchemaRegistry, createObjectQLKernel, utilities) is now available directly from `@objectstack/objectql`.
+
+The `ObjectQLPlugin` (orchestrator composing sub-plugins like ValidatorPlugin, FormulaPlugin, QueryPlugin) remains in this package as it is specific to the `@objectql` ecosystem.
 
 ## Features
 

packages/foundation/core/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@objectql/core",
   "version": "4.2.1",
-  "description": "Universal runtime engine for ObjectQL - AI-native metadata-driven ORM with validation, repository pattern, and driver orchestration",
+  "deprecated": "Use @objectstack/objectql instead. See https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx",
+  "description": "DEPRECATED — Use @objectstack/objectql. Plugin orchestrator for ObjectQL sub-plugins (validator, formula, query).",
   "keywords": [
     "objectql",
     "orm",

packages/foundation/core/src/index.ts

@@ -1,21 +1,29 @@
 /**
- * ObjectQL
+ * ObjectQL Core — DEPRECATED
  * Copyright (c) 2026-present ObjectStack Inc.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
+ *
+ * @deprecated This package is deprecated. Migrate to `@objectstack/objectql`.
+ * See: https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx
  */
 
-// ── Convenience factory ──
-export { createObjectQLKernel, type ObjectQLKernelOptions } from './kernel-factory';
-
-// ── Re-export bridge engine (extends upstream with MetadataRegistry + legacy config) ──
+// ── Bridge engine (deprecated — use @objectstack/objectql ObjectQL directly) ──
+/** @deprecated Import ObjectQL from `@objectstack/objectql` instead. This bridge class will be removed in a future version. */
 export { ObjectQL, type ObjectQLConfig } from './app';
+
+// ── Convenience factory (local implementation — wraps upstream kernel) ──
+export { createObjectQLKernel } from './kernel-factory';
+export type { ObjectQLKernelOptions } from './kernel-factory';
+
+// ── Re-exports from @objectstack/objectql (deprecated — import directly from upstream) ──
+/** @deprecated Import from `@objectstack/objectql` instead. */
 export { ObjectRepository, ScopedContext, SchemaRegistry } from '@objectstack/objectql';
+/** @deprecated Import from `@objectstack/objectql` instead. */
+export { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
+/** @deprecated Import from `@objectstack/objectql` instead. */
 export type { HookHandler, HookEntry, OperationContext, EngineMiddleware, ObjectQLHostContext } from '@objectstack/objectql';
 
-// ── Plugin orchestration ──
+// ── Plugin orchestration (downstream — stays in @objectql ecosystem) ──
 export * from './plugin';
-
-// ── Utilities ──
-export * from './util';

packages/foundation/platform-node/package.json

@@ -27,7 +27,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/types": "workspace:*",
     "@objectstack/spec": "^3.0.4",
     "fast-glob": "^3.3.2",

packages/foundation/platform-node/src/loader.ts

@@ -11,7 +11,7 @@ import * as glob from 'fast-glob';
 import * as path from 'path';
 import { MetadataRegistry, ObjectConfig, LoaderPlugin, LoaderHandlerContext, FieldConfig } from '@objectql/types';
 import * as yaml from 'js-yaml';
-import { toTitleCase } from '@objectql/core';
+import { toTitleCase } from '@objectstack/objectql';
 
 export class ObjectLoader {
     private plugins: LoaderPlugin[] = [];

packages/tools/cli/package.json

@@ -30,6 +30,7 @@
   },
   "dependencies": {
     "@objectql/types": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/core": "workspace:*",
     "@objectql/plugin-validator": "workspace:*",
     "@objectql/driver-sql": "workspace:*",

packages/tools/cli/src/commands/doctor.ts

@@ -208,6 +208,7 @@ async function checkDependencies(packageJson: any): Promise<DependencyCheck[]> {
 
     // Check for ObjectQL core packages
     const corePackages = [
+        '@objectstack/objectql',
         '@objectql/core',
         '@objectql/types',
         '@objectql/cli'

packages/tools/cli/src/commands/migrate.ts

@@ -27,7 +27,7 @@ interface MigrateStatusOptions {
     dir?: string;
 }
 
-const MIGRATION_TEMPLATE = `import { ObjectQL } from '@objectql/core';
+const MIGRATION_TEMPLATE = `import { ObjectQL } from '@objectstack/objectql';
 
 /**
  * Migration: {{name}}

packages/tools/cli/src/commands/repl.ts

@@ -9,7 +9,7 @@
 import * as repl from 'repl';
 import * as _path from 'path';
 import * as _fs from 'fs';
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { register } from 'ts-node';
 import { resolveConfigFile } from '../utils/config-loader';
 
@@ -83,7 +83,7 @@ export async function startRepl(configPath?: string) {
                     get: () => {
                         // Dynamic require to avoid circular dependency — ObjectRepository is constructed
                         // from the user-provided app instance to enable convenient REPL access.
-                        const { ObjectRepository } = require('@objectql/core');
+                        const { ObjectRepository } = require('@objectstack/objectql');
 
                         const replContext: any = {
                             roles: ['admin'],