Implement runtime plugin system with dependency resolution and query pipeline

[Copilot]

Implements the runtime layer for plugin management and query processing, maintaining strict separation from protocol definitions in @objectql/types.

New Package: @objectql/runtime-core

PluginManager

• Topological sort for dependency resolution
• Detects circular and missing dependencies
• Lifecycle management (setup/teardown in dependency order)

QueryPipeline

• Async series waterfall pattern for query transformation
• Three-phase execution: validation → beforeQuery → execute → afterQuery
• Each plugin receives output from previous plugin

Runtime Factory

• createRuntime(config) entrypoint
• Integrates PluginManager and QueryPipeline
• Simple API for initialization and query execution

Type Extensions

Enhanced @objectql/types with:

• BasePlugin - metadata, dependencies, lifecycle hooks
• QueryProcessorPlugin - validateQuery, beforeQuery, afterQuery
• PluginMetadata - name, version, type, dependencies

Usage

import { createRuntime } from '@objectql/runtime-core';
import type { QueryProcessorPlugin } from '@objectql/types';

const securityPlugin: QueryProcessorPlugin = {
  metadata: {
    name: 'security',
    type: 'query_processor',
    dependencies: ['logger']
  },
  async beforeQuery(query, context) {
    // Waterfall: transform and pass to next plugin
    return {
      ...query,
      filters: [...(query.filters || []), ['tenant_id', '=', context.user?.tenant_id]]
    };
  }
};

const runtime = createRuntime({ plugins: [securityPlugin, loggerPlugin] });
runtime.setQueryExecutor(driver.execute);
await runtime.init(); // Initializes in dependency order: logger → security

const results = await runtime.query('project', { filters: [['status', '=', 'active']] });

Key Algorithms

Topological Sort: Depth-first traversal with cycle detection, ensures correct initialization order regardless of registration order.

Async Waterfall: Each plugin in pipeline receives previous plugin's output, enabling composition patterns like query enrichment and result decoration.

Original prompt

在重新讨论任务时，我们需要清晰地区分协议层 (Protocol/Spec) 和运行时/实现层 (Runtime/Implementation) 的职责边界。根据 IMPLEMENTATION_ROADMAP.md 和 PACKAGE_RESTRUCTURING.md 的规划，以及 PluginManager 这个具体任务，分析如下：

1. 应该在协议层 (@objectstack/spec) 约定的

协议层的核心目标是定义标准和契约，确保不同插件、不同语言实现之间的一致性。

• 插件元数据接口 (PluginMetadata): 插件的名称格式、版本规范、类型枚举（driver, repository 等）是跨语言通用的概念，已经在 PR feat: Phase 1 - Establish plugin architecture foundation with @objectql/types v4.0.0 #150 的 @objectql/types 中定义，但更底层的 PluginInterface 应该遵循 @objectstack/spec 中的定义（如果有）。
• 错误码与异常契约 (ErrorCode): 当插件加载失败、依赖缺失或循环依赖时，系统抛出的错误码应该在 Spec 中标准化，以便统一监控和处理。
• 核心生命周期事件名: 虽然具体 Hooks 实现是在运行时，但生命周期的阶段名称（如 setup, teardown, beforeQuery）应该作为标准常量定义在 Spec 中。

2. 应该在当前任务 (ObjectQL Runtime) 处理的

当前任务是实现，即将协议转化为可运行的代码。这部分逻辑是 Node.js/TypeScript 特定的。

• 插件加载逻辑 (PluginManager):
  • 依赖解析与拓扑排序: 这是纯粹的运行时算法逻辑，负责计算插件的启动顺序。这是当前任务的核心。
  • 插件注册表: 在内存中维护 Map<PluginName, PluginInstance>。
  • 上下文注入: 将 Runtime 实例注入到插件的 setup() 方法中。
• 查询执行编排 (QueryExecutor):
  • 管道模式 (Pipeline): 实现如何按顺序调用 validateQuery -> beforeQuery -> driver.execute -> afterQuery 的流程控制。
  • 中间件执行: 处理异步 Hooks 的串行或并行执行。
• 具体类实现: ObjectStackEngine 或 ObjectQL 入口类的实例化逻辑。

调整后的任务重点

鉴于此，我们可以微调下一个任务的 Prompt，使其更加聚焦于运行时实现，同时确保它正确引用了已有的协议定义，而不是重复定义。

核心区别：不要在 Runtime 里重新定义 "什么是插件"（这是 Type/Spec 的事），而是去实现 "如何加载和运行插件"。

修正后的 Prompt 建议

我建议将之前的 Prompt 优化为：

---

Context: 我们已经完成了基础类型定义（@objectql/types），定义了 QueryProcessorPlugin 等接口。现在需要实现运行时逻辑来驱动这些接口。

Goal: 在 packages/core/runtime 中实现核心的插件系统和查询执行器。

Design Principles:

• Implementation-only: 不要重复定义接口，直接引入 @objectql/types。
• DI (Dependency Injection): 插件管理器应作为核心服务，供 QueryExecutor 调用。

Tasks:

1. Package Setup: 初始化 packages/core/runtime。

2. PluginManager Implementation:

   • 实现 register(plugin)：接收符合 BasePlugin 接口的插件。
   • 实现 resolveDependencies()：使用拓扑排序算法解决插件依赖顺序（如果插件 A 依赖 B，B 必须先 setup）。
   • 实现 boot()：按顺序调用插件的 setup(runtime) 方法。

3. QueryPipeline Implementation:

   • 实现一个 Pipeline 类，能够接收一个 UnifiedQuery。
   • 它需要从 PluginManager 获取所有注册的 QueryProcessorPlugin。
   • 关键逻辑: 实现 AsyncSeriesWaterfall 钩子执行模式 —— beforeQuery 的输出作为下一个插件的输入。

4. Runtime Entrypoint:

   • 实现 createRuntime(config) 工厂函数，返回一个包含 pluginManager 和 query() 方法的实例。

Deliverable:

• 包含单元测试，演示：注册两个互相依赖的插件，并验证 setup 调用顺序正确。

---

这样更符合“协议-实现分离”的架构原则。

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

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

Project	Deployment	Review	Updated (UTC)
objectql-site	Ready	Preview, Comment	Jan 21, 2026 1:12pm

[github-actions]

⚠️ No Changeset Found

This PR does not include a changeset file.
If this PR includes user-facing changes, please add a changeset by running:

pnpm changeset

[github-actions]

⚠️ No Changeset Found

This PR does not include a changeset file.
If this PR includes user-facing changes, please add a changeset by running:

pnpm changeset