Document @objectql/core deprecation and plugin architecture

[Copilot]

The upstream @objectql/core package has been deprecated (objectstack-ai/objectql#373) for violating @objectstack/spec microkernel principles. This repository is already compliant—it uses @objectstack/objectql with explicit plugin composition.

Changes

ROADMAP.md (+155 lines)

• Added "Architecture Migration" section documenting 4-phase deprecation plan (v4.3 → v5.0)
• Defined terminal state: pure plugin marketplace (core plugins, protocol adapters, platform adapters, drivers)
• Clarified ObjectUI's compliant implementation with concrete examples

README.md (+48 lines)

• Added "Plugin Architecture" section contrasting explicit vs deprecated patterns
• Listed best practices for plugin developers

Pattern Difference

// ❌ Deprecated (magic aggregator from @objectql/core)
new ObjectQLPlugin({
  enableRepository: true,
  enableQueryService: true,
  enableValidator: true,
  // ...hidden complexity
})

// ✅ Explicit (current ObjectUI implementation)
import { ObjectQLPlugin } from '@objectstack/objectql';
import { DriverPlugin, AppPlugin } from '@objectstack/runtime';

plugins: [
  new ObjectQLPlugin(),
  new DriverPlugin(new InMemoryDriver()),
  new AppPlugin(config),
  new HonoServerPlugin({ port: 3000 }),
  new ConsolePlugin(),
]

No code changes required—documentation only.

Original prompt

背景

根据 objectstack-ai/objectql 仓库中已完成的 @objectql/core 重构（PR #373），@objectql/core 已从 ~3,500 LOC 瘦身至 734 LOC 的 thin bridge + plugin orchestrator，并且 package.json 已标注 deprecated。

宪法依据：@objectstack/spec 是上游协议规范，所有开发必须遵循此协议。当前 @objectql/core 的残余中间层违背了 ObjectStack 微内核 + 插件架构的设计哲学。

任务

1. 更新 Roadmap

在项目的 Roadmap 文档中添加/更新以下迁移计划：

目标：彻底作废 @objectql/core，本项目以纯插件生态形态存在。

迁移阶段：

Phase A: 消灭 ObjectQLPlugin 聚合器 (v4.3)

• 将 @objectql/core 中的 plugin.ts（323 LOC 聚合器）拆散
• 消费者从 new ObjectQLPlugin({ enableRepository, enableQueryService, enableValidator, enableFormulas, datasources }) 一键启用
• 迁移为显式组合各独立插件：

  // 目标形态 — 显式、透明、无魔法
  import { ObjectQLPlugin } from '@objectstack/objectql';       // 上游数据引擎
  import { QueryPlugin } from '@objectql/plugin-query';
  import { ValidatorPlugin } from '@objectql/plugin-validator';
  import { FormulaPlugin } from '@objectql/plugin-formula';

Phase B: 处置 Bridge Class (v4.3)

• 将 app.ts（168 LOC bridge class）的 MetadataRegistry 桥接逻辑移入 @objectql/platform-node
• ObjectLoader 直接注册到上游 SchemaRegistry，不再需要中间层

Phase C: 处置其余模块 (v4.3)

• kernel-factory.ts → 删除，用户直接 new ObjectStackKernel([...plugins])
• repository.ts → 删除，直接 import { ObjectRepository } from '@objectstack/objectql'
• util.ts → 移入 @objectql/types（纯函数，与类型包定位一致）

Phase D: v5.0 Breaking Release (Q4 2026)

• 彻底删除 @objectql/core 包内容
• 发布 @objectql/core@5.0.0 作为空壳 meta-package
  • 仅 peerDependencies 指向各子插件
  • 运行时输出 console.warn 迁移提示
• 更新所有文档、examples、tests

终极形态 — 纯插件市场：

@objectql/plugin-query           # 查询增强
@objectql/plugin-validator       # 声明式校验
@objectql/plugin-formula         # 计算字段
@objectql/plugin-security        # RBAC/FLS/RLS
@objectql/plugin-optimizations   # 性能优化
@objectql/plugin-workflow        # 状态机
@objectql/plugin-multitenancy    # 多租户
@objectql/plugin-sync            # 数据同步
@objectql/protocol-graphql       # GraphQL 协议
@objectql/protocol-odata-v4      # OData V4 协议
@objectql/protocol-json-rpc      # JSON-RPC 协议
@objectql/platform-node          # Node.js 平台适配
@objectql/edge-adapter           # Edge Runtime 适配
@objectql/driver-*               # 各数据库驱动
@objectql/types                  # 宪法 (不变)

2. 开始执行迁移

在可行的范围内开始执行 Phase A 的初步工作：

• 更新项目中引用 @objectql/core 的代码，改为直接引用上游包或独��插件包
• 如果有 objectstack.config.ts 或类似配置文件，将 ObjectQLPlugin 的一键组合模式改为显式插件列表模式
• 更新相关文档和 README

风险缓解

• 保留向后兼容的 re-export 直到 v5.0
• 提供 createObjectQLPreset() 便利函数返回推荐插件组合（可选）
• 文档明确声明推荐的插件注册顺序

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectui	Ready	Preview, Comment	Feb 16, 2026 1:50pm
objectui-demo	Ready	Preview, Comment	Feb 16, 2026 1:50pm
objectui-storybook	Ready	Preview, Comment	Feb 16, 2026 1:50pm