diff --git a/docs/WAVELET_DEVELOPER_GUIDE.md b/docs/WAVELET_DEVELOPER_GUIDE.md
index 30703d09..3f9b894a 100644
--- a/docs/WAVELET_DEVELOPER_GUIDE.md
+++ b/docs/WAVELET_DEVELOPER_GUIDE.md
@@ -313,6 +313,16 @@ SELECT * FROM w_schema_versions ORDER BY plugin_id, version_id;
---
### 场景 12:如何发布和订阅领域事件 (EventBus)?
+Wavelet 完整实现了 Cordis 架构的 **4 种类型化事件分发语义**,支持同步管道、并发聚合与异步广播:
+
+| 分发方法 | 分发语义 | 返回值/错误处理 | 适用场景 |
+| :--- | :--- | :--- | :--- |
+| `ctx.Events().Emit(ctx, topic, payload)` | **异步广播 (Broadcast)** | 不阻塞主流程,静默恢复 handler panic | 状态变更广播、审计日志记录、跨插件解耦通知 |
+| `ctx.Events().Waterfall(ctx, topic, initial)` | **流式管道 (Waterfall)** | 依次将前一个 handler 返回值传给下一个,遇错立即短路退出 | 参数过滤拦截链、内容审查、数据清洗与加工 |
+| `ctx.Events().Parallel(ctx, topic, payload)` | **并发聚合 (Parallel)** | 并发启动 goroutine 执行所有 handler,用 `errors.Join` 聚合所有错误 | 并发外部系统推送、多渠道并行通知校验 |
+| `ctx.Events().Serial(ctx, topic, payload)` | **串行执行 (Serial)** | 按注册顺序依次同步执行,遇到首个非 nil 错误立即短路中断 | 敏感操作前置拦截(如权限/风控准入校验) |
+
+#### 1. 异步广播 (`Emit`) 与订阅 (`On`)
```go
// 1. 定义强类型事件结构
type OrderPaidEvent struct {
@@ -321,8 +331,8 @@ type OrderPaidEvent struct {
PayAmount int64 `json:"pay_amount"`
}
-// 2. 插件 A 发布事件
-ctx.Events().Emit("order:paid", OrderPaidEvent{OrderID: "ord_1", UserID: "u_1", PayAmount: 9900})
+// 2. 插件 A 发布事件(广播)
+ctx.Events().Emit(ctx, "order:paid", OrderPaidEvent{OrderID: "ord_1", UserID: "u_1", PayAmount: 9900})
// 3. 插件 B 订阅事件
ctx.Events().On("order:paid", func(c context.Context, e OrderPaidEvent) error {
@@ -331,6 +341,35 @@ ctx.Events().On("order:paid", func(c context.Context, e OrderPaidEvent) error {
})
```
+#### 2. 流式管道变换 (`Waterfall`)
+Handler 支持返回 `(T, error)` 或 `T`,后续 Handler 接收上一 Handler 的返回值:
+```go
+// 插件注册拦截处理
+ctx.Events().On("content:filter", func(c context.Context, text string) (string, error) {
+ return strings.ReplaceAll(text, "敏感词", "***"), nil
+})
+
+// 调用方通过 Waterfall 获得流式处理后的结果
+cleaned, err := ctx.Events().Waterfall(ctx, "content:filter", "原始文本包含敏感词")
+// cleaned == "原始文本包含***"
+```
+
+#### 3. 串行准入拦截 (`Serial`)
+```go
+// 风控插件注册校验
+ctx.Events().On("order:pre_create", func(c context.Context, req CreateOrderRequest) error {
+ if isBlacklisted(req.UserID) {
+ return errors.New("用户处于风控黑名单,禁止下单")
+ }
+ return nil
+})
+
+// 订单插件执行准入链,遇到首个错误立即中断并返回
+if err := ctx.Events().Serial(ctx, "order:pre_create", req); err != nil {
+ return err // 拦截创建
+}
+```
+
---
### 场景 13:如何向系统注册插件自定义配置(config.yaml 与管理台热加载设置)?
@@ -574,18 +613,21 @@ Wavelet/
| 扩展点方法 | 返回类型 | 功能说明 | 适用场景 |
| :--- | :--- | :--- | :--- |
-| `ctx.Router()` | `RouterExtension` | 声明 HTTP 路由、前缀分组与挂载中间件 | 暴露 API 接口、Web 控制台 |
-| `ctx.Task()` | `TaskExtension` | 注册 Asynq 异步任务消费处理器 | 耗时后台任务、异步消息发送 |
-| `ctx.Schedule()` | `ScheduleExtension`| 注册 Cron 定时调度任务 | 定时报表统计、周期性清理 |
-| `ctx.Migrations()` | `MigrationExtension`| 注册插件专属的 Goose SQL 迁移嵌入系统 | 自建数据表、版本升级 |
-| `ctx.Events()` | `EventBus` | 强类型领域事件的发布与订阅 (Emit / On) | 跨插件完全解耦通知与状态同步 |
-| `ctx.Settings()` | `SettingExtension` | 声明动态可配置项(支持热更新) | 业务参数配置、管理台可调节参数 |
-| `ctx.DB()` | `*gorm.DB` | 获取全局受事务与 Trace 保护的 GORM 数据源 | 数据持久化 CRUD |
-| `ctx.Cache()` | `CacheService` | 三层穿透缓存(RAM L1 + Redis L2 + PubSub 广播)| 高频读数据性能加速 |
+| `ctx.Router()` | `RouterExtension` | 声明 HTTP 路由、前缀分组与挂载中间件,支持 `Unregister` / `UnregisterByID` | 暴露 API 接口、Web 控制台 |
+| `ctx.Task()` | `TaskExtension` | 注册 Asynq 异步任务消费处理器,支持 `Unregister` | 耗时后台任务、异步消息发送 |
+| `ctx.Schedule()` | `ScheduleExtension`| 注册 Cron 定时调度任务,支持 `Unregister` | 定时报表统计、周期性清理 |
+| `ctx.Migrations()` | `MigrationExtension`| 注册插件专属的 Goose SQL 迁移嵌入系统,支持 `Unregister` | 自建数据表、版本升级 |
+| `ctx.Events()` | `EventBus` | 强类型领域事件总线(支持 `Emit`, `Waterfall`, `Parallel`, `Serial`) | 跨插件完全解耦通知与状态同步 |
+| `ctx.Settings()` | `SettingExtension` | 声明动态可配置项(支持热更新),支持 `Unregister` | 业务参数配置、管理台可调节参数 |
+| `ctx.DB()` | `contracts.DBService` | 获取受事务与 Trace 保护的数据库连接与 GORM 实例 | 数据持久化 CRUD |
+| `ctx.Cache()` | `contracts.CacheService` | 三层穿透缓存(RAM L1 + Redis L2 + PubSub 广播)| 高频读数据性能加速 |
| `ctx.DistLock()` | `DistLockService` | 基于 Redis 的工业级分布式锁 | 防并发超卖、防重复执行 |
| `ctx.Logger()` | `Logger` | 携带链路 TraceID 的结构化日志记录器 | 业务日志打印与审计 |
-| `ctx.Storage()` | `StorageService` | 统一对象存储读写引擎 | 文件摄取、图片持久化 |
-| `core.Provide[T]`| `void` | 向全局 IoC 容器注册本插件提供的强类型服务 | 暴露自身能力给其他插件消费 |
+| `ctx.Storage()` | `contracts.StorageService` | 统一对象存储读写引擎 | 文件摄取、图片持久化 |
+| `ctx.Fork()` | `*Context` | 创建继承父级容器并隔离局部副作用的子上下文 | 局部 Fiber、请求域隔离 |
+| `core.Provide[T]`| `void` | 向全局 IoC 容器注册强类型服务(自动挂载 `OnDispose` 逆操作) | 暴露自身能力给其他插件消费 |
| `core.Inject[T]` | `(T, error)` | 从全局 IoC 容器中按类型获取服务实例 | 消费其他插件暴露的服务 |
+| `core.When[T]` | `void` | 响应式监听服务注入(当服务一旦就绪立即触发回调) | 解决插件装载时序竞争与延迟初始化 |
+| `core.Has[T]` | `bool` | 判断指定服务类型当前是否已在容器中注册 | 探测环境能力与条件装载 |
| `core.Using[T]` | `error` | 响应式声明依赖,当服务就绪时执行回调 | 声明前置依赖关系 |
diff --git a/docs/WAVELET_WHITE_PAPER.md b/docs/WAVELET_WHITE_PAPER.md
index fa99359f..e727a55a 100644
--- a/docs/WAVELET_WHITE_PAPER.md
+++ b/docs/WAVELET_WHITE_PAPER.md
@@ -34,12 +34,19 @@ Wavelet 是面向未来 5 年生产级云原生与高并发业务中台的 **微
ctx.Provide(Auth) ctx.Using([DB, Cache]) ctx.Route / ctx.Task
```
-### 2.1 微内核原则 (Micro-Kernel Principle)
+### 2.1 时空可组合性与微内核原则 (Spatiotemporal Composability & Micro-Kernel)
+Wavelet 贯彻了 Cordis 核心范式,通过形式化保证解决组件系统的两大正交难题:
+
+| 维度 | 含义 | Wavelet Cordis 工程实现 |
+| :--- | :--- | :--- |
+| **时间可组合性** | 组件卸载后,对共享环境的修改必须能完全、按序撤销 | **可逆副作用 (Revertible Effects)**:扩展点(Router/Task/Schedule/Setting/Migration)与 `core.Provide` 服务注册均内建逆操作记账,卸载时按 LIFO 回收 |
+| **空间可组合性** | 组件声明的边界与依赖必须严格隔离与响应式通知 | **响应式余效应 (Reactive Coeffects) 与作用域上下文**:`core.Inject`/`core.When` 声明依赖并支持时序响应;`ctx.Fork()` 创建隔离作用域 |
+
内核(`core/`)不持有任何具体业务逻辑,不硬编码 Gin、GORM、Asynq 等具体引擎。内核仅提供:
- 树状上下文(`Context`)与作用域隔离(`Fork`)
-- 泛型依赖注入与服务定位器(`IoC Container`)
-- 强类型领域事件总线(`EventBus`)
-- 生命周期编排器(`Lifecycle Manager`)与标准扩展点契约
+- 泛型依赖注入与服务定位器(`core.Provide`, `core.Inject`, `core.When`, `core.Has`, `core.Using`)
+- 4 种类型化分发语义的领域事件总线(`Emit` 异步广播, `Waterfall` 流式管道, `Parallel` 并发聚合, `Serial` 串行短路)
+- 生命周期编排器(`Lifecycle Manager`)与可逆扩展点契约(`extpoints`)
### 2.2 扁平自包含插件 (Flat & Self-Contained Plugins)
告别过度设计的样板代码,每个插件作为一个自给自足的高内聚闭包,就近组织路由、Handler、模型与专属数据迁移,实现**随插随用、按需组合、随拔随走**。
@@ -60,8 +67,8 @@ Wavelet 是面向未来 5 年生产级云原生与高并发业务中台的 **微
▼
+-----------------------------------------------------------------------------------+
| Wavelet Core (微内核上下文总线) |
-| - Context (服务树与扩展点总线) - Lifecycle Manager (生命周期编排) |
-| - Service Hub (泛型 IoC 容器) - EventBus (强类型领域事件总线) |
+| - Context (服务树与可逆扩展点总线) - Lifecycle Manager (生命周期编排) |
+| - Service Hub (泛型 IoC 容器) - EventBus (4 种分发语义事件总线) |
+-----------------------------------------------------------------------------------+
│ │
▼ 注册与驱动 ▼ 挂载能力
@@ -93,7 +100,7 @@ Wavelet 是面向未来 5 年生产级云原生与高并发业务中台的 **微
4. **`plugins/` 单所有者原则与数据迁移独立性 (100% Pass)**:
- 每个业务插件自包含专有 `migrations/00001_initial.sql`,通过 `go:embed` 注册。
- 所有插件共享 `w_schema_versions` 表,以 `plugin_id` 列区分版本,彻底消除单体大迁移目录合并冲突,杜绝 GORM AutoMigrate。
- - `pkg/migrator/` 全局迁移目录已物理删除,26 个全局 SQL 文件全部分配至对应插件。
+ - `domain/admin` 对用户和认证源的全部操作 100% 委托给 `contracts.UserService` 与 `contracts.AuthService`,严禁旁路越权读写。
5. **并发与生命周期析构安全 (100% Pass)**:
- 全局遵循 LIFO (后进先出) Disposer 逆序优雅注销机制。在开启 `-race` 竞争检测下,所有事件并发广播、多协程注入与读写均 0 数据竞争。
@@ -103,13 +110,14 @@ Wavelet 是面向未来 5 年生产级云原生与高并发业务中台的 **微
| 测试模块 / 核心功能 | 测试方法与输入条件 | 预期结果 (Expected) | 实际测试输出与指标 | 判定 |
| :--- | :--- | :--- | :--- | :--- |
-| **(1) Context 泛型服务注入** | `TestContextProvideAndInject`
通过 `core.Provide[T]` 注册服务,并发调用 `core.Inject[T]` 与 `core.Using[T]` | 强类型精准匹配,服务就绪后回调自动触发,类型安全且无反射类型错误 | **PASS**
毫秒级响应,0 数据竞争 | ✅ 通过 |
-| **(2) 强类型 EventBus 广播** | `TestEventBusPublishSubscribe`
并发注册泛型 Handler 与指针结构体 Handler,高并发广播 `Emit(ctx, topic, payload)` | 事件精准投递至对应订阅者,自动解包类型;Panic 自动 Recover 并收集为 errors.Join | **PASS**
1000+ 并发广播 0 丢失,无 Race 报错 | ✅ 通过 |
-| **(3) HTTP Driver 动态路由级联** | `TestRouterExtension`
插件注册多级路由前缀(`/api/v1/oauth`, `/api/v1/admin`, `/api/v1/upload`)与中间件链 | 路由树自动合并,中间件按洋葱模型正确拦截执行 | **PASS**
状态码 200/401 按预期拦截响应 | ✅ 通过 |
-| **(4) Asynq Worker 并发消费** | `TestAsynqWorkerDriverLifecycle`
注册 `message_gateway:push_notification` 与 `upload:cleanup_expired` 任务,启动 Worker 驱动并投递异步任务 | Worker 成功拉起消费池,执行 TaskHandler 并反馈结果;Stop(ctx) 优雅等待任务完成 | **PASS**
任务平滑执行,优雅停机 0 悬挂协程 | ✅ 通过 |
-| **(5) Asynq Cron 定时调度** | `TestAsynqCronDriverLifecycle`
注册 `0 3 * * *` 定时规则,启动 Scheduler 驱动 | 定时器正确解析 Spec,准时调度投递 Payload | **PASS**
调度器生命周期启停无异常 | ✅ 通过 |
-| **(6) 自包含 Goose SQL 迁移** | `TestAppMigrationEngineExecution`
收集各插件 `embed.FS`,由 MigrationEngine 按插件依赖顺序联合执行 | 自动创建版本记录表,按版本号依序执行迁移脚本,无跨插件冲突 | **PASS**
SQL 语法兼容 PostgreSQL 与 SQLite | ✅ 通过 |
-| **(7) App 运行切面与平滑停机** | `TestAppProfileDispatch`
分别以 `api` / `worker` / `schedule` / `all` Profile 启动 App | 仅拉起当前 Profile 所需的 Driver 驱动,其余保持休眠;捕获 SIGINT 逆序注销 | **PASS**
切面过滤 100% 精准,停机耗时 < 50ms | ✅ 通过 |
+| **(1) Context 泛型服务注入** | `TestContextProvideAndInject`
通过 `core.Provide[T]` 注册服务,并发调用 `core.Inject[T]`、`core.When[T]` 与 `core.Using[T]` | 强类型精准匹配,服务就绪后回调自动触发,卸载时自动注销清理 | **PASS**
毫秒级响应,0 数据竞争 | ✅ 通过 |
+| **(2) 4 种类型化 EventBus 语义** | `TestEventBusWaterfall`, `TestEventBusParallel`, `TestEventBusSerial`
高并发执行异步广播、流式管道转换与串行准入拦截 | 事件精准投递;管道正确传递返回值与短路;Panic 自动 Recover 并聚合错误 | **PASS**
1000+ 并发广播 0 丢失,无 Race 报错 | ✅ 通过 |
+| **(3) 可逆扩展点注销与生命周期** | `TestExtensionPointsUnregister`
动态注册路由、任务、调度、配置、迁移后调用 `Unregister` / `UnregisterByID` | 注册项从全局与局部作用域完整移除,副作用完全回收 | **PASS**
注销状态与长度验证 100% 匹配 | ✅ 通过 |
+| **(4) HTTP Driver 动态路由级联** | `TestRouterExtension`
插件注册多级路由前缀(`/api/v1/oauth`, `/api/v1/admin`, `/api/v1/upload`)与中间件链 | 路由树自动合并,中间件按洋葱模型正确拦截执行 | **PASS**
状态码 200/401 按预期拦截响应 | ✅ 通过 |
+| **(5) Asynq Worker 并发消费** | `TestAsynqWorkerDriverLifecycle`
注册 `message_gateway:push_notification` 与 `upload:cleanup_expired` 任务,启动 Worker 驱动并投递异步任务 | Worker 成功拉起消费池,执行 TaskHandler 并反馈结果;Stop(ctx) 优雅等待任务完成 | **PASS**
任务平滑执行,优雅停机 0 悬挂协程 | ✅ 通过 |
+| **(6) Asynq Cron 定时调度** | `TestAsynqCronDriverLifecycle`
注册 `0 3 * * *` 定时规则,启动 Scheduler 驱动 | 定时器正确解析 Spec,准时调度投递 Payload | **PASS**
调度器生命周期启停无异常 | ✅ 通过 |
+| **(7) 自包含 Goose SQL 迁移** | `TestAppMigrationEngineExecution`
收集各插件 `embed.FS`,由 MigrationEngine 按插件依赖顺序联合执行 | 自动创建版本记录表,按版本号依序执行迁移脚本,无跨插件冲突 | **PASS**
SQL 语法兼容 PostgreSQL 与 SQLite | ✅ 通过 |
+| **(8) App 运行切面与平滑停机** | `TestAppProfileDispatch`
分别以 `api` / `worker` / `schedule` / `all` Profile 启动 App | 仅拉起当前 Profile 所需的 Driver 驱动,其余保持休眠;捕获 SIGINT 逆序注销 | **PASS**
切面过滤 100% 精准,停机耗时 < 50ms | ✅ 通过 |
---