Implement realtime sync, event bus, and job scheduling protocols

[Copilot]

Adds three core system protocols for ObjectStack's metadata-driven runtime: realtime synchronization, event-driven architecture, and job scheduling.

Realtime Sync Protocol (realtime.zod.ts)

• Transport-agnostic subscriptions via WebSocket/SSE/polling
• Event filtering at subscription level
• Presence tracking with custom metadata

const subscription: Subscription = {
  id: '550e8400-e29b-41d4-a716-446655440000',
  events: [
    { type: 'record.updated', object: 'opportunity', filters: { stage: 'closed_won' } }
  ],
  transport: 'websocket',
  channel: 'sales-pipeline'
};

Event Bus Protocol (events.zod.ts)

• Wildcard event patterns (user.*, *.created)
• Priority-based handler execution with async/sync modes
• Event routing with optional transformation
• Configurable persistence with retention policies

const route: EventRoute = {
  from: 'order.completed',
  to: ['email.send', 'inventory.update', 'analytics.track'],
  transform: (payload) => ({ ...payload, processedAt: Date.now() })
};

Job Scheduling Protocol (job.zod.ts)

• Discriminated union for cron/interval/once scheduling
• Exponential backoff retry policy
• Timezone-aware cron with standard expressions

const job: Job = {
  id: 'backup-daily',
  name: 'daily_backup',
  schedule: { type: 'cron', expression: '0 2 * * *', timezone: 'America/New_York' },
  retryPolicy: { maxRetries: 3, backoffMs: 1000, backoffMultiplier: 2 },
  timeout: 1800000,
  handler: async () => { /* implementation */ }
};

Coverage

• 101 test cases (32 realtime, 29 events, 40 jobs)
• 100% coverage on all schemas
• JSON schemas and MDX docs auto-generated

Original prompt

任务 1.2: 实时同步协议

文件: packages/spec/src/system/realtime.zod.ts
负责人: 系统架构师
工作量: 4 天
依赖: 无

实现要点:

// 1. 传输层选择
export const TransportProtocol = z.enum([
'websocket', // 全双工，低延迟
'sse', // Server-Sent Events，单向推送
'polling', // 短轮询，兼容性最好
]);

// 2. 事件订阅
export const SubscriptionSchema = z.object({
id: z.string().uuid(),
events: z.array(z.object({
type: z.enum(['record.created', 'record.updated', 'record.deleted', 'field.changed']),
object: z.string().optional().describe('Object name to subscribe to'),
filters: z.any().optional().describe('Filter conditions'),
})),
transport: TransportProtocol,
channel: z.string().optional(),
});

// 3. 在线状态
export const PresenceSchema = z.object({
userId: z.string(),
status: z.enum(['online', 'away', 'offline']),
lastSeen: z.string().datetime(),
metadata: z.record(z.any()).optional().describe('Custom presence data'),
});

// 4. 同步事件
export const RealtimeEventSchema = z.object({
id: z.string().uuid(),
type: z.string(),
object: z.string().optional(),
action: z.enum(['created', 'updated', 'deleted']).optional(),
payload: z.any(),
timestamp: z.string().datetime(),
userId: z.string().optional(),
});
验收标准:

Schema 定义完成
测试覆盖率 ≥ 80% (至少 25 个测试用例)
支持 WebSocket、SSE、Polling 三种传输层
事件过滤和路由逻辑清晰
文档包含实际使用示例
测试重点:

事件类型枚举完整性
订阅过滤器验证
传输层配置验证
在线状态转换逻辑
Sprint 2 (Week 3-4) - 事件总线和任务调度

任务 2.1: 事件总线协议

文件: packages/spec/src/system/events.zod.ts
负责人: 系统架构师
工作量: 3 天
依赖: 无

实现要点:

// 1. 事件定义
export const EventSchema = z.object({
name: z.string().regex(/^[a-z_][a-z0-9_.]*$/),
payload: z.any().describe('Event payload schema'),
metadata: z.object({
source: z.string().describe('Event source (e.g., plugin name)'),
timestamp: z.string().datetime(),
userId: z.string().optional(),
tenantId: z.string().optional(),
}),
});

// 2. 事件处理器
export const EventHandlerSchema = z.object({
eventName: z.string(),
handler: z.function().args(EventSchema).returns(z.promise(z.void())),
priority: z.number().int().default(0).describe('Lower numbers execute first'),
async: z.boolean().default(true).describe('Execute in background'),
});

// 3. 事件路由
export const EventRouteSchema = z.object({
from: z.string().describe('Source event pattern (supports wildcards)'),
to: z.array(z.string()).describe('Target event names'),
transform: z.function().optional().describe('Transform payload'),
});

// 4. 持久化配置
export const EventPersistenceSchema = z.object({
enabled: z.boolean().default(false),
retention: z.number().int().positive().describe('Days to retain events'),
filter: z.function().optional().describe('Filter which events to persist'),
});
验收标准:

Schema 定义完成
测试覆盖率 ≥ 80%
支持事件路由和转换
支持优先级和异步执行
文档清晰
任务 2.2: 任务调度协议

文件: packages/spec/src/system/job.zod.ts
负责人: 系统架构师
工作量: 3 天
依赖: 事件总线协议 (可选)

实现要点:

// 1. 调度策略
export const ScheduleSchema = z.discriminatedUnion('type', [
z.object({
type: z.literal('cron'),
expression: z.string().describe('Cron expression (e.g., "0 0 * * *")'),
timezone: z.string().optional().default('UTC'),
}),
z.object({
type: z.literal('interval'),
intervalMs: z.number().int().positive(),
}),
z.object({
type: z.literal('once'),
at: z.string().datetime(),
}),
]);

// 2. 任务定义
export const JobSchema = z.object({
id: z.string(),
name: z.string().regex(/^[a-z_][a-z0-9_]*$/),
schedule: ScheduleSchema,
handler: z.function().returns(z.promise(z.void())),
retryPolicy: z.object({
maxRetries: z.number().int().min(0).default(3),
backoffMs: z.number().int().positive().default(1000),
backoffMultiplier: z.number().positive().default(2),
}).optional(),
timeout: z.number().int().positive().optional().describe('Timeout in ms'),
enabled: z.boolean().default(true),
});

// 3. 任务执行日志
export const JobExecutionSchema = z.object({
jobId: z.string(),
startedAt: z.string().datetime(),
completedAt: z.string().datetime().optional(),
status: z.enum(['running', 'success', 'failed', 'timeout']),
error: z.string().optional(),
duration: z.number().int().optional().describe('Duration in ms'),
});
验收标准:

支持 Cron、Interval、Once 三种调度策略
重试策略完整 (指数退避)
测试覆盖率 ≥ 80%
文档包含实际 Cron 表达式示例

---

💡 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)
spec	Ready	Preview, Comment	Jan 23, 2026 6:49am

[github-actions]

This PR is very large. Consider breaking it into smaller PRs for easier review.

[Copilot]

Pull request overview

Adds new ObjectOS system protocols (Realtime Sync, Event Bus, Job Scheduling) to packages/spec, including Zod schemas, Vitest coverage, and generated JSON Schema + MDX reference pages.

Changes:

• Introduces new Zod protocols: realtime, events, and job under packages/spec/src/system.
• Adds comprehensive Vitest suites for the new protocols and exports them via packages/spec/src/system/index.ts.
• Generates corresponding JSON Schema artifacts and MDX reference documentation pages.

Reviewed changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/spec/src/system/realtime.zod.ts	Adds realtime sync protocol schemas (transport, subscriptions, presence, events).
packages/spec/src/system/realtime.test.ts	Adds Vitest coverage for realtime protocol schemas.
packages/spec/src/system/events.zod.ts	Adds event bus protocol schemas (event, handler, routes, persistence).
packages/spec/src/system/events.test.ts	Adds Vitest coverage for event bus protocol schemas.
packages/spec/src/system/job.zod.ts	Adds job scheduling protocol schemas (schedule union, retry policy, execution logs).
packages/spec/src/system/job.test.ts	Adds Vitest coverage for job scheduling protocol schemas.
packages/spec/src/system/index.ts	Exports the newly added system protocols.
packages/spec/json-schema/TransportProtocol.json	JSON Schema output for TransportProtocol.
packages/spec/json-schema/SubscriptionEvent.json	JSON Schema output for SubscriptionEvent.
packages/spec/json-schema/Subscription.json	JSON Schema output for Subscription.
packages/spec/json-schema/RealtimeEventType.json	JSON Schema output for RealtimeEventType.
packages/spec/json-schema/PresenceStatus.json	JSON Schema output for PresenceStatus.
packages/spec/json-schema/Presence.json	JSON Schema output for Presence.
packages/spec/json-schema/RealtimeAction.json	JSON Schema output for RealtimeAction.
packages/spec/json-schema/RealtimeEvent.json	JSON Schema output for RealtimeEvent.
packages/spec/json-schema/CronSchedule.json	JSON Schema output for CronSchedule.
packages/spec/json-schema/IntervalSchedule.json	JSON Schema output for IntervalSchedule.
packages/spec/json-schema/OnceSchedule.json	JSON Schema output for OnceSchedule.
packages/spec/json-schema/Schedule.json	JSON Schema output for Schedule union.
packages/spec/json-schema/RetryPolicy.json	JSON Schema output for RetryPolicy.
packages/spec/json-schema/Job.json	JSON Schema output for Job.
packages/spec/json-schema/JobExecutionStatus.json	JSON Schema output for JobExecutionStatus.
packages/spec/json-schema/JobExecution.json	JSON Schema output for JobExecution.
packages/spec/json-schema/EventMetadata.json	JSON Schema output for EventMetadata.
packages/spec/json-schema/Event.json	JSON Schema output for Event.
packages/spec/json-schema/EventHandler.json	JSON Schema output for EventHandler.
packages/spec/json-schema/EventRoute.json	JSON Schema output for EventRoute.
packages/spec/json-schema/EventPersistence.json	JSON Schema output for EventPersistence.
content/docs/references/system/TransportProtocol.mdx	MDX reference page for TransportProtocol.
content/docs/references/system/SubscriptionEvent.mdx	MDX reference page for SubscriptionEvent.
content/docs/references/system/Subscription.mdx	MDX reference page for Subscription.
content/docs/references/system/RealtimeEventType.mdx	MDX reference page for RealtimeEventType.
content/docs/references/system/PresenceStatus.mdx	MDX reference page for PresenceStatus.
content/docs/references/system/Presence.mdx	MDX reference page for Presence.
content/docs/references/system/RealtimeAction.mdx	MDX reference page for RealtimeAction.
content/docs/references/system/RealtimeEvent.mdx	MDX reference page for RealtimeEvent.
content/docs/references/system/CronSchedule.mdx	MDX reference page for CronSchedule.
content/docs/references/system/IntervalSchedule.mdx	MDX reference page for IntervalSchedule.
content/docs/references/system/OnceSchedule.mdx	MDX reference page for OnceSchedule.
content/docs/references/system/Schedule.mdx	MDX reference page for Schedule (currently empty).
content/docs/references/system/RetryPolicy.mdx	MDX reference page for RetryPolicy.
content/docs/references/system/Job.mdx	MDX reference page for Job.
content/docs/references/system/JobExecutionStatus.mdx	MDX reference page for JobExecutionStatus.
content/docs/references/system/JobExecution.mdx	MDX reference page for JobExecution.
content/docs/references/system/EventMetadata.mdx	MDX reference page for EventMetadata.
content/docs/references/system/Event.mdx	MDX reference page for Event.
content/docs/references/system/EventHandler.mdx	MDX reference page for EventHandler.
content/docs/references/system/EventRoute.mdx	MDX reference page for EventRoute.
content/docs/references/system/EventPersistence.mdx	MDX reference page for EventPersistence.

Comments suppressed due to low confidence (1)

content/docs/references/system/Schedule.mdx:6

• This reference page is empty (no details on the discriminated union variants). Since ScheduleSchema is a core public protocol type, the docs should describe each variant (cron, interval, once) and their required fields, or the doc generator should be updated so union schemas render properly.

---
title: Schedule
description: Schedule Schema Reference
---

[Copilot]

EventRouteSchema.transform is declared as z.function() without .args(...)/.returns(...), so the inferred type becomes overly permissive ((...args: any[]) => any) and loses useful contract validation. Define the expected signature (e.g., (payload) => payload) with .args(...) and .returns(...) to keep the protocol self-describing and type-safe.

[Copilot]

EventPersistenceSchema.filter is typed as a bare z.function() with no argument/return contract, which makes it hard to understand/validate what the filter should receive and return. Consider constraining it to something like (event: Event) => boolean via .args(EventSchema).returns(z.boolean()).

[Copilot]

timezone uses .optional().default('UTC'). In Zod, .default(...) already makes the field optional, so the extra .optional() is redundant and inconsistent with other schemas in this repo (e.g., QueryContextSchema.timezone uses .default('UTC') without .optional()).