Complete development plan: modularize kernel/events.zod.ts, add v3.0 migration guide by Copilot · Pull Request #611 · objectstack-ai/framework

Copilot · 2026-02-11T06:29:22Z

Sprint K: Modularize kernel/events.zod.ts (765 lines → 6 sub-modules) with backward-compatible re-exports
Phase 8: Create v3.0 migration guide document (V3_MIGRATION_GUIDE.md)
Phase 8: Update CHANGELOG.md with breaking changes for v3.0
Update ROADMAP.md to reflect current completion status
Update PROTOCOL_OPTIMIZATION_REPORT.md with Sprint K completion and final status
Run all tests to verify no regressions (175 files, 4518 tests pass)
Code review — all feedback addressed
Security scan — no vulnerabilities found

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

vercel · 2026-02-11T06:29:27Z

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

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Canceled		Feb 11, 2026 7:34am
spec	Error		Feb 11, 2026 7:34am

Split 765-line events.zod.ts into 6 focused sub-modules: - events/core.zod.ts: Priority, metadata, type definition, base event - events/handlers.zod.ts: Event handlers, routes, persistence - events/queue.zod.ts: Queue config, replay, sourcing - events/dlq.zod.ts: Dead letter queue, event log entries - events/integrations.zod.ts: Webhooks, message queues, notifications - events/bus.zod.ts: Complete event bus config and helpers Backward-compatible: events.zod.ts now re-exports from sub-modules. All 175 test files (4518 tests) pass. Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

- Created V3_MIGRATION_GUIDE.md with comprehensive migration paths - Updated CHANGELOG.md with unreleased changes - Updated ROADMAP.md Phase 5/8 checklist items - Updated PROTOCOL_OPTIMIZATION_REPORT.md: Sprint K completed, all A-K done Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot

Pull request overview

Modularizes the kernel event-bus protocol into smaller Zod sub-modules and adds/updates documentation to support the planned v3.0 migration narrative.

Changes:

Split kernel/events.zod.ts into multiple focused modules under kernel/events/ and kept events.zod.ts as a backward-compatible re-export barrel.
Added packages/spec/V3_MIGRATION_GUIDE.md describing breaking changes and migration steps for v3.0.
Updated roadmap/report/changelog docs to mark milestones complete and reflect updated test counts.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/spec/src/kernel/events/core.zod.ts	New core event schemas (priority, metadata, base event, type definition).
packages/spec/src/kernel/events/handlers.zod.ts	New handler/route/persistence schemas.
packages/spec/src/kernel/events/queue.zod.ts	New queue/replay/sourcing configuration schemas.
packages/spec/src/kernel/events/dlq.zod.ts	New DLQ + event log entry schemas.
packages/spec/src/kernel/events/integrations.zod.ts	New webhook/message-queue/realtime integration schemas.
packages/spec/src/kernel/events/bus.zod.ts	New top-level event bus config schema (+ helper functions).
packages/spec/src/kernel/events/index.ts	New barrel file for event sub-modules.
packages/spec/src/kernel/events.zod.ts	Replaced monolith with re-exports from the new sub-modules.
packages/spec/V3_MIGRATION_GUIDE.md	New migration guide for v3.0 changes and mappings.
ROADMAP.md	Updated phase checklist and metrics (test file/test count, modularization progress).
PROTOCOL_OPTIMIZATION_REPORT.md	Marked Sprint K (events modularization) and overall sprint completion as done.
CHANGELOG.md	Added unreleased notes for events modularization + migration guide.

Copilot · 2026-02-11T06:54:55Z

+ * This file re-exports all event schemas from modular sub-modules for backward compatibility.
+ * New code should import directly from sub-modules in `./events/` for better tree-shaking.
 * 


The doc comment claims new code should import directly from ./events/ sub-modules for better tree-shaking, but @objectstack/spec currently only exports the ./kernel subpath and the build bundles kernel/index (no separate kernel/events/* entrypoints). This makes the suggested consumer import style misleading unless package exports/build are updated. Consider either (a) exposing ./kernel/events/* as real entrypoints via package.json exports + tsup entry, or (b) adjusting the comment to clarify these sub-modules are an internal source-code organization detail and should still be imported via @objectstack/spec/kernel.

Suggested change

* This file re-exports all event schemas from modular sub-modules for backward compatibility.

* New code should import directly from sub-modules in `./events/` for better tree-shaking.

*

* This file re-exports all event schemas from modular sub-modules for backward compatibility

* and to provide a single stable entrypoint for consumers (via `@objectstack/spec/kernel`).

*

* NOTE: The `./events/*` sub-modules referenced below are an internal source-code organization

* detail of the kernel. External code should continue to import event schemas from the

* published kernel entrypoint, for example:

*

* import { EventBusSchema } from '@objectstack/spec/kernel';

*

* and SHOULD NOT import from `@objectstack/spec/kernel/events/*` unless those paths are

* explicitly documented as public entrypoints in the package exports.

*

Updated in 45ee05c. The doc comment now clarifies that ./events/* sub-modules are an internal source-code organization detail and consumers should import from @objectstack/spec/kernel.

Copilot · 2026-02-11T06:54:56Z

+| Category | Change | Impact |
+|----------|--------|--------|
+| Hub Module Removal | `Hub.*` namespace removed from barrel exports | Medium |
+| Runtime Logic Extraction | `createErrorResponse()`, `getHttpStatusForCategory()`, `definePlugin()` removed from spec | Medium |
+| Deprecated Field Removal | `location` (singular) removed from ActionSchema | Low |
+| Deprecated Schema Aliases | `RealtimePresenceStatus`, `RealtimeAction`, `RateLimitSchema` removed | Low |
+


The tables are written with a leading double pipe (||), which renders as an extra empty column (or fails to render cleanly) in standard GitHub-flavored Markdown. Update these to use standard pipe table syntax (| ... |) so the guide renders correctly.

Checked the table syntax — the tables in the guide use standard | ... | pipe syntax and render correctly in GitHub-flavored Markdown. No leading double-pipe issues found.

Copilot · 2026-02-11T06:54:56Z

+import { RateLimitSchema } from '@objectstack/spec/api/endpoint';
+
+// ✅ v3.0 canonical location
+import { RateLimitConfigSchema } from '@objectstack/spec/shared/http';


These import examples use deep subpath specifiers (@objectstack/spec/api/endpoint and @objectstack/spec/shared/http), but the package exports currently only exposes top-level subpaths like ./api and ./kernel. With an exports map present, deep imports will fail for consumers unless those subpaths are explicitly exported. Either change the examples to supported imports (e.g. from @objectstack/spec/api / @objectstack/spec/shared) or add the corresponding exports entries in packages/spec/package.json.

Suggested change

import { RateLimitSchema } from '@objectstack/spec/api/endpoint';

// ✅ v3.0 canonical location

import { RateLimitConfigSchema } from '@objectstack/spec/shared/http';

import { RateLimitSchema } from '@objectstack/spec/api';

// ✅ v3.0 canonical location

import { RateLimitConfigSchema } from '@objectstack/spec/shared';

Fixed in 45ee05c. Updated import examples to use top-level subpaths (@objectstack/spec/api and @objectstack/spec/shared) which match the published exports in package.json.

Copilot · 2026-02-11T06:54:56Z

+// ✅ Preferred: Direct sub-module import for better tree-shaking
+import { EventBusConfigSchema } from '@objectstack/spec/kernel/events/bus';
+import { EventSchema, EventPriority } from '@objectstack/spec/kernel/events/core';
+import { EventWebhookConfigSchema } from '@objectstack/spec/kernel/events/integrations';


These examples recommend importing from @objectstack/spec/kernel/events/*, but the package does not currently export ./kernel/events/* subpaths and the build outputs a bundled kernel/index entry. As written, these imports will not resolve for consumers unless you add explicit exports entries and build entrypoints for each kernel/events/* module. Update the examples or expose these subpaths.

Fixed in 45ee05c. Rewrote the events section to clarify the restructuring is internal — no migration needed, consumers continue importing from @objectstack/spec/kernel. Removed all @objectstack/spec/kernel/events/* examples.

Copilot · 2026-02-11T06:54:56Z

+ * Event Bus Protocol - Modular Sub-modules
+ * 
+ * This barrel re-exports all event sub-modules for convenient importing.
+ * 
+ * Sub-modules:
+ * - core.zod.ts: Event priority, metadata, type definition, base event
+ * - handlers.zod.ts: Event handlers, routes, persistence
+ * - queue.zod.ts: Event queue, replay, sourcing configuration
+ * - dlq.zod.ts: Dead letter queue, event log entries
+ * - integrations.zod.ts: Webhooks, message queues, real-time notifications
+ * - bus.zod.ts: Complete event bus configuration and helper functions
+ */
+
+export * from './core.zod';
+export * from './handlers.zod';
+export * from './queue.zod';
+export * from './dlq.zod';
+export * from './integrations.zod';
+export * from './bus.zod';


This kernel/events/index.ts barrel is not referenced by kernel/events.zod.ts or any current entrypoint, and @objectstack/spec does not export a ./kernel/events subpath. As a result it is likely unused and won’t be emitted in dist, which can confuse maintainers. Consider removing it, or wiring it up as an actual public entrypoint (tsup entry + package.json exports) if you want @objectstack/spec/kernel/events imports to work.

Suggested change

* Event Bus Protocol - Modular Sub-modules

*

* This barrel re-exports all event sub-modules for convenient importing.

*

* Sub-modules:

* - core.zod.ts: Event priority, metadata, type definition, base event

* - handlers.zod.ts: Event handlers, routes, persistence

* - queue.zod.ts: Event queue, replay, sourcing configuration

* - dlq.zod.ts: Dead letter queue, event log entries

* - integrations.zod.ts: Webhooks, message queues, real-time notifications

* - bus.zod.ts: Complete event bus configuration and helper functions

*/

export * from './core.zod';

export * from './handlers.zod';

export * from './queue.zod';

export * from './dlq.zod';

export * from './integrations.zod';

export * from './bus.zod';

* Event Bus Protocol - Kernel Events

*

* NOTE:

* - Canonical Zod schemas live in the sibling `*.zod.ts` files

* (e.g. `core.zod.ts`, `handlers.zod.ts`, `queue.zod.ts`, `dlq.zod.ts`,

* `integrations.zod.ts`, `bus.zod.ts`).

* - Public entrypoints MUST be wired via `tsup` `entry` and `package.json`

* `exports` (for example through `kernel/events.zod.ts`), not by relying

* on this file as a barrel.

*

* This file intentionally exports nothing to avoid defining an implicit

* `@objectstack/spec/kernel/events` subpath that is not part of the

* published API surface.

*/

Fixed in 45ee05c. Replaced the barrel re-exports with a doc-only comment explaining this file is not part of the published API surface and @objectstack/spec/kernel/events is not an exported subpath.

Copilot · 2026-02-11T06:54:57Z

+export function createEventBusConfig<T extends z.input<typeof EventBusConfigSchema>>(config: T): T {
+  return config;
+}
+
+/**
+ * Helper to create event type definition
+ */
+export function createEventTypeDefinition<T extends z.input<typeof EventTypeDefinitionSchema>>(definition: T): T {
+  return definition;
+}
+
+/**
+ * Helper to create event webhook configuration
+ */
+export function createEventWebhookConfig<T extends z.input<typeof EventWebhookConfigSchema>>(config: T): T {
+  return config;
+}


This file introduces new runtime helper functions (createEventBusConfig, createEventTypeDefinition, createEventWebhookConfig). Given the ongoing direction to keep @objectstack/spec declarative and move runtime helpers to @objectstack/core (as documented in the migration guide), these helpers should either be avoided here or explicitly marked @deprecated with a clear removal plan/location (or moved to core now) to prevent expanding the runtime surface area of the spec package.

Fixed in 45ee05c. All three helper functions (createEventBusConfig, createEventTypeDefinition, createEventWebhookConfig) are now marked @deprecated with direction to move to @objectstack/core and removal in v3.0.0.

hotlong · 2026-02-11T07:09:42Z

@copilot fix all

@deprecated

- events.zod.ts: clarify sub-modules are internal, not public entrypoints - events/index.ts: replace barrel exports with doc-only comment noting this is not a published API surface - events/bus.zod.ts: mark helper functions @deprecated for v3.0 removal - V3_MIGRATION_GUIDE.md: fix import paths to use top-level subpaths (./api, ./shared) instead of deep paths; rewrite events section to clarify internal restructuring requires no migration Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot · 2026-02-11T07:13:02Z

@copilot fix all

All 6 review comments addressed in 45ee05c. All 175 test files (4518 tests) pass.

Initial plan

d4becf7

Copilot AI assigned Copilot and hotlong Feb 11, 2026

Copilot started work on behalf of hotlong February 11, 2026 06:29 View session

Copilot AI and others added 2 commits February 11, 2026 06:38

Copilot AI changed the title ~~[WIP] Update development plan with protocol optimization report~~ Complete development plan: modularize kernel/events.zod.ts, add v3.0 migration guide Feb 11, 2026

Copilot AI requested a review from hotlong February 11, 2026 06:46

Copilot finished work on behalf of hotlong February 11, 2026 06:46

hotlong approved these changes Feb 11, 2026

View reviewed changes

hotlong marked this pull request as ready for review February 11, 2026 06:48

Copilot AI review requested due to automatic review settings February 11, 2026 06:48

Copilot started reviewing on behalf of hotlong February 11, 2026 06:49 View session

github-actions Bot added documentation Improvements or additions to documentation size/xl labels Feb 11, 2026

Copilot AI reviewed Feb 11, 2026

View reviewed changes

Copilot started work on behalf of hotlong February 11, 2026 07:10 View session

Copilot AI requested a review from hotlong February 11, 2026 07:13

Copilot finished work on behalf of hotlong February 11, 2026 07:13

vercel Bot had a problem deploying to Preview – spec February 11, 2026 07:25 Failure

hotlong merged commit 746bcd3 into main Feb 11, 2026
1 of 3 checks passed

vercel Bot deployed to Preview – objectstack-play February 11, 2026 07:34 View deployment

- * This file re-exports all event schemas from modular sub-modules for backward compatibility.
- * New code should import directly from sub-modules in `./events/` for better tree-shaking.
- *
+ * This file re-exports all event schemas from modular sub-modules for backward compatibility
+ * and to provide a single stable entrypoint for consumers (via `@objectstack/spec/kernel`).
+ *
+ * NOTE: The `./events/*` sub-modules referenced below are an internal source-code organization
+ * detail of the kernel. External code should continue to import event schemas from the
+ * published kernel entrypoint, for example:
+ *
+ *   import { EventBusSchema } from '@objectstack/spec/kernel';
+ *
+ * and SHOULD NOT import from `@objectstack/spec/kernel/events/*` unless those paths are
+ * explicitly documented as public entrypoints in the package exports.
+ *

Conversation

Copilot AI commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

hotlong commented Feb 11, 2026

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 11, 2026 •

edited

Loading

vercel Bot commented Feb 11, 2026 •

edited

Loading