cordis-testkit 0.0.0-stage → 0.1.0

package/DESIGN.md

@@ -0,0 +1,191 @@
+# cordis-testkit —— 设计说明
+
+> 非官方测试替身。不是 Cordis 官方实现，不隶属 cordiverse / DeepSeek。Apache-2.0。
+
+## 1. 问题
+
+写 Cordis 插件单测时，真实 `Context` 会把 fiber、依赖注入、服务反射、配置校验、HMR 等一起带进来。测试通常只关心三件事：
+
+1. 我注册的 listener 能不能被事件触发？
+2. 我通过 `ctx.effect()` / `ctx.plugin()` 申请的资源，在 `dispose()` 时有没有被释放？
+3. 测试结束时，有没有漏掉的 listener/effect/plugin？
+
+真运行时的这些机制会掩盖简单的泄漏：context 一销毁，所有资源都没了，测试不会告诉你**插件是否真的自己管理了生命周期**。本包用一个可观察的资源表替代运行时，专门回答上面三个问题。
+
+## 2. 目标与非目标
+
+### 目标
+
+- `createMockContext()` 提供与 Cordis 形似的 `on` / `emit` / `effect` / `set` / `get` / `plugin` / `dispose`。
+- 所有注册都进表，可快照、可断言。
+- `dispose()` 逆序执行 cleanup、清空 listener，且重复调用幂等。
+- `assertNoLeaks()` 给出**分类 + 名称**的泄漏清单，而不只是 boolean。
+- 纯 ESM + JSDoc，零第三方依赖，Node 22/24 可离线跑。
+- 明确声明非官方、命名状态和限制，避免被误当成 Cordis 发行版。
+
+### 非目标
+
+- 不做 Cordis 运行时（无 fiber、inject、service、reflect、HMR）。
+- 不做异步 effect / Promise cleanup / async iterator。
+- 不做事件系统的完整语义（once、prepend、parallel/serial/waterfall、过滤）。
+- 不做配置 schema 校验；config 原样传给插件。
+- 不做性能优化或跨线程安全；它是测试工具，单线程同步即可。
+
+## 3. 数据模型
+
+每个 context 持有内部状态（挂在 `Symbol.for('cordis-testkit.state')` 上，避免污染公开字段）：
+
+```text
+{
+  listeners: ListenerRecord[],   // { event, callback, active }
+  effects:   EffectRecord[],     // { label, active, disposed, cleanup }
+  plugins:   PluginRecord[],     // { name, active, disposed, cleanup }
+  cleanups:  CleanupEntry[],     // LIFO：{ kind:'effect'|'plugin', record }
+  store:     Map,                // set/get
+  disposed:  boolean,
+  sequence:  number              // 默认 effect/plugin 名称
+}
+```
+
+为什么 listener 不进 cleanup 栈？因为 listener 的「释放」只是从表中删除，没有用户 cleanup 回调；而 effect/plugin 可能带用户函数，必须在 `dispose()` 中按逆序调用。listener 表在所有 cleanup 完成后统一清空，保证 cleanup 期间仍可通过返回的 disposer 删除 listener。
+
+`snapshot()` 只暴露活跃资源的**名称**（listener 是 event，effect 是 label，plugin 是 name），因为：
+
+- 测试断言通常只关心「哪个资源没清」；
+- 不把内部 record 暴露出去，避免测试依赖实现细节；
+- 返回新数组，调用方修改快照不会污染 context。
+
+## 4. 生命周期
+
+### 4.1 注册
+
+- `ctx.on(event, cb)`：校验 event 为 string/symbol、cb 为函数；压入 listener；返回幂等 disposer。
+- `ctx.effect(fn, label)`：先建 record 和 LIFO entry，再**同步执行** `fn`。
+  - `fn` 返回函数：保存为 cleanup。
+  - 返回 `undefined` / `null`：合法的无 cleanup effect，仍算活跃资源（严格模式）。
+  - 返回其他值（包括 Promise）：抛 `TypeError`，并回滚 record/entry，不留下幽灵注册。
+  - `fn` 自身抛错：同样回滚后重抛。
+- `ctx.plugin(plugin, config)`：校验插件形态，记录名称，同步 apply。
+  - 函数插件：`plugin(ctx, config)`，`this = ctx`。
+  - 对象插件：`plugin.apply(ctx, config)`，`this = plugin`。
+  - 返回函数：作为 plugin cleanup；其他非空返回值抛 `TypeError`（明确不支持异步插件）。
+  - apply 抛错：移除 plugin record 后重抛。已经注册到 context 的 listener/effect 仍保留，由调用方 `ctx.dispose()` 清理；`runPlugin()` 会自动做这件事。
+  - 成功后压入 plugin 的 LIFO entry，使 plugin cleanup 先于它注册的 effect 执行。
+
+`ctx.plugin()` 返回 `ctx`（便于链式调用），而不是 Cordis 的 fiber 句柄。这是已知差异，README 中列明。
+
+### 4.2 事件
+
+`ctx.emit(event, ...args)` 先复制 listener 数组，再逐个检查 `active` 和 event 匹配：
+
+- emit 期间新增的 listener 不会在本轮触发；
+- emit 期间被移除的 listener 会跳过；
+- 某个 listener 抛错会立即中断本轮并向上抛，与 Cordis 的同步 emit 行为一致；
+- `this` 绑定为 mock context，方便插件里的普通函数写法；
+- 返回值是 listener 结果数组，仅为测试便利（Cordis 返回 void）。
+
+### 4.3 释放
+
+`ctx.dispose()`：
+
+```text
+if (already disposed) return
+disposed = true
+while (cleanups 非空):
+  entry = cleanups.pop()          // LIFO
+  if effect: disposeEffect(record)
+  if plugin: disposePlugin(record)
+清空 listeners（标记 inactive）
+清空 effects/plugins 表
+若有 cleanup 错误: 抛 AggregateError(errors, ...)
+```
+
+关键点：
+
+- **先执行再清表**：cleanup 期间还能通过保存的 disposer 释放 listener；所有 cleanup 结束后才统一清空。
+- **错误不短路**：所有 cleanup 都会跑；错误收集后一次抛出。这样即使一个 cleanup 写错，也不会让后面的资源滞留。
+- **幂等**：`disposed = true` 在第一次进入时立即设置；即使第一次抛 `AggregateError`，第二次调用也直接返回。`dispose()` 也可从 cleanup 内部安全调用（空操作）。
+- **record 级幂等**：`disposeEffect` / `disposePlugin` 在调用 cleanup 前先置 `disposed = true`；effect 返回的 disposer 也通过 `removed` 标记保证只执行一次。
+
+### 4.4 泄漏判定
+
+`assertNoLeaks(ctx)`：
+
+1. `snapshot(ctx)`；
+2. 三类都为空 → 返回；
+3. 否则构造 `Error`，message 含每类的计数与名称，附 `code = 'ERR_CORDIS_LEAK'` 和 `leaks = snapshot`。
+
+判定的是「活跃注册」而不是 `disposed` 标志，因此两种测试写法都成立：
+
+```js
+// A. 释放整个 context
+ctx.dispose()
+assertNoLeaks(ctx)
+
+// B. 逐个释放，context 仍活着
+const off = ctx.on('tick', fn)
+off()
+assertNoLeaks(ctx)
+```
+
+effect 即使没有 cleanup 也算活跃：这会让「注册了但没人负责」在测试里显形，而不是静默通过。代价是偏向严格，README 已注明。
+
+## 5. 与 Cordis 4 的兼容面
+
+| 能力 | Cordis 4 | cordis-testkit |
+|---|---|---|
+| `ctx.on` 返回 disposer | 是 | 是 |
+| listener `this` | 事件派发约定 | 绑定 ctx（模拟便利） |
+| `ctx.effect` 立即执行 | 是 | 是 |
+| effect cleanup 逆序 | 是 | 是 |
+| effect 支持 Promise/iterator | 是 | **否**（同步替身） |
+| `ctx.plugin` 子 fiber | 是 | **否**，同 ctx |
+| plugin 返回 cleanup | 支持 effect 语义 | 只支持同步函数 |
+| `ctx.emit` 返回 | void | 结果数组（便利） |
+| `ctx.plugin` 返回 | fiber 句柄 | ctx |
+| inject/provide/reflect/service | 是 | 否 |
+| `once`/`prepend`/`parallel`/`waterfall` | 是 | 否 |
+| HMR / update / restart | 是 | 否 |
+| 配置校验 | 是 | 否（原样传递） |
+
+这张表就是本包的「不要误用」清单。需要真实行为时请用官方 `cordis`。
+
+## 6. 命名与法律
+
+- 官方项目：`cordiverse/cordis`；官方 npm 包：`cordis`（核验时 `4.0.0-rc.13`）。
+- `cordis-testkit` 于 2026-11-14 查询 npm registry 返回 404；官方 `packages/` 列表无 `testkit`。因此它不是官方保留名或官包，只是当前未被占用的社区名。
+- 同类名 `@cordisjs/testkit`、`cordis-test-utils`、`@cordisjs/test-utils`、`cordis-mock` 当时也均为 404。
+- 本包不复用官方源码；官方是 MIT，本包是 Apache-2.0。名称与商标归各自权利人。
+- DeepSeek Harness 生态中带 `@deepseek-ai/*testkit` scope 的包与本包无关。
+
+更完整的查询命令与证据见 README「命名核验」。
+
+## 7. 测试策略
+
+测试用 `node:test`，按行为分层：
+
+- `test/context.test.js`：on/emit、过滤与顺序、set/get、listener disposer、snapshot 副本、dispose 后禁止注册。
+- `test/effects.test.js`：立即执行、cleanup、逆序、disposer 幂等、setup 失败回滚、cleanup 错误汇总、无 cleanup effect 仍计活跃。
+- `test/leaks.test.js`：dispose 后通过、listener/effect/plugin 三类泄漏、清单完整性、显式释放也可通过、非法 ctx。
+- `test/plugin.test.js`：函数/对象插件、config、plugin cleanup 顺序、plugin 资源释放、runPlugin、apply 失败自动清理、非法返回值。
+
+当前共 **27 个测试**，运行：
+
+```sh
+node --test packages/cordis-testkit/test/*.test.js
+node --check packages/cordis-testkit/src/core.js
+```
+
+## 8. 迭代方向（未实现）
+
+- 可选开启的异步 effect/cleanup（保持默认同步）；
+- plugin 级 dispose 句柄（当前只能整体 dispose）；
+- listener options（prepend/once）与事件过滤；
+- 与真实 Cordis 的 contract test（同一组断言分别在 mock 与真 ctx 上跑）；
+- 更细的泄漏归因（哪个 plugin 注册了哪个资源）。
+
+这些都需要先确认不会把「简单可预测的测试替身」做成半个运行时。当前版本刻意保持小。
+
+## 9. License
+
+Apache-2.0，见 [LICENSE](./LICENSE)。

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# cordis-testkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 是什么
+
+> **非官方项目**：这是社区独立编写的 **Cordis 测试替身（test double）**，不是 Cordis 官方实现，也不由 cordiverse / Cordis 作者背书。  
+> 与 DeepSeek 同样没有隶属关系。本包代码使用 **Apache-2.0**；Cordis 本身是 cordiverse 的 MIT 项目。
+
+`cordis-testkit` 给 Cordis 插件测试提供两件事：
+
+1. **一个可预测的 mock context**：可以手动 `emit` 事件、注册/释放 listener、effect 和 plugin；
+2. **资源泄漏断言**：`assertNoLeaks(ctx)` 会列出没清理的 listener / effect / plugin，并让测试失败。
+
+它面向单元测试，不试图复刻 Cordis 运行时。
+
+## 为什么
+
+Cordis 插件的约定是「通过 `ctx` 注册的东西，由 `ctx.dispose()` 统一释放」。但用一个真实 Cordis 实例测插件，会同时引入 fiber、依赖注入、服务反射、配置解析等大量与本次测试无关的行为。很多泄漏（忘了 return effect cleanup、listener 没随插件释放）在普通断言里也看不出来。
+
+这个包把 `ctx` 缩成一张资源表：
+
+- 测试需要的事件派发：`on` / `emit`；
+- 测试需要的生命周期：`effect` / `plugin` / `dispose`；
+- 测试需要的状态：`set` / `get` / `snapshot`；
+- 测试需要的验收：`assertNoLeaks`。
+
+## 安装
+
+0.1.0，**尚未发布到 npm**。在本仓库内直接使用：
+
+```sh
+cd packages/cordis-testkit
+npm test
+node --check src/core.js
+```
+
+发布后才可用：
+
+```sh
+npm install --save-dev cordis-testkit
+```
+
+要求 Node `^22.19.0 || >=24.9.0`。纯 ESM，无第三方依赖，可离线测试。
+
+本包**没有 CLI**，因此没有进程退出码契约；测试通过/失败由 `node:test` 与
+`assertNoLeaks` 抛错决定（`error.code = 'ERR_CORDIS_LEAK'`）。
+
+## 用法
+
+```js
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  assertNoLeaks,
+  createMockContext,
+  runPlugin,
+  snapshot,
+} from 'cordis-testkit'
+
+test('plugin registers and releases its timer', () => {
+  const ctx = runPlugin((inner, config) => {
+    inner.effect(() => {
+      const timer = setInterval(() => {}, config.interval)
+      return () => clearInterval(timer)
+    }, 'timer')
+  }, { interval: 1000 })
+
+  assert.deepEqual(snapshot(ctx).effects, ['timer'])
+  ctx.dispose()
+  assertNoLeaks(ctx)
+})
+```
+
+事件：
+
+```js
+const ctx = createMockContext()
+const seen = []
+
+ctx.on('ready', (value) => seen.push(value))
+ctx.emit('ready', 42)
+assert.deepEqual(seen, [42])
+
+ctx.dispose()
+assertNoLeaks(ctx)
+```
+
+泄漏测试（故意失败）：
+
+```js
+const ctx = createMockContext()
+ctx.on('tick', () => {})
+
+assert.throws(
+  () => assertNoLeaks(ctx),
+  (error) => {
+    assert.equal(error.code, 'ERR_CORDIS_LEAK')
+    assert.match(error.message, /listener/)
+    assert.match(error.message, /tick/)
+    return true
+  },
+)
+```
+
+`error.leaks` 是结构化清单：
+
+```js
+{ listeners: ['tick'], effects: [], plugins: [], disposed: false }
+```
+
+### API
+
+| API | 说明 |
+|---|---|
+| `createMockContext()` | 创建 `MockContext`。所有注册都记录在 context 内。 |
+| `ctx.on(event, cb)` | 注册 listener。`event` 为 string 或 symbol；返回幂等 disposer。 |
+| `ctx.emit(event, ...args)` | 同步派发。listener 以 `ctx` 为 `this`。返回 listener 返回值数组（见「与 Cordis 的差异」）。 |
+| `ctx.effect(fn, label?)` | 立即执行 `fn`，接收其同步 cleanup。返回幂等 disposer。默认标签 `effect#N`。 |
+| `ctx.set(key, value)` / `ctx.get(key)` | 简单的 `Map` 存储，用于断言插件读到的配置/服务。 |
+| `ctx.plugin(plugin, config?)` | 同步应用函数插件或 `{ name, apply }` 对象插件，记录 plugin 名称。返回 `ctx`。 |
+| `ctx.dispose()` | 逆序释放 cleanup，清空 listener/effect/plugin 表。幂等。cleanup 错误汇总为 `AggregateError`。 |
+| `snapshot(ctx)` | 返回 `{ listeners, effects, plugins, disposed }`；数组只含**仍活跃**资源，且是副本。 |
+| `assertNoLeaks(ctx)` | 有活跃 listener/effect/plugin 时抛 `Error`，带分类清单；全部释放则通过。 |
+| `runPlugin(plugin, config?)` | `createMockContext()` + `ctx.plugin()`，返回 live ctx；apply 抛错时先释放半成品再抛出。 |
+
+### 释放顺序
+
+`dispose()` 维护一条 LIFO cleanup 栈：
+
+1. effect 的 cleanup 按**注册逆序**执行（后注册先清理）；
+2. plugin 成功 apply 后登记自己的 cleanup，因此它会先于它注册的 effect 执行；
+3. 所有 cleanup 跑完后才清空 listener 表；
+4. 某个 cleanup 抛错不会中断其余 cleanup；全部跑完后抛 `AggregateError`，`error.code = 'ERR_CORDIS_DISPOSE'`。
+5. 第一次 `dispose()` 即使抛错，context 也已标记 disposed，后续调用直接返回（幂等）。
+
+### 泄漏判定
+
+`assertNoLeaks(ctx)` 检查的是**仍活跃的注册**，不是「是否调用过 dispose」：
+
+- `ctx.dispose()` 之后一定通过；
+- 从未 dispose、但每个 listener/effect 都用返回的 disposer 释放了，也通过；
+- 一个 effect 即使没有返回 cleanup，只要没释放仍算活跃资源（严格模式，避免「注册了却没人管」）；
+- plugin 只要 apply 成功、尚未 dispose，就算活跃 plugin。
+
+## 限制
+
+### 与 Cordis 的差异（重要限制）
+
+这是为测试写的**同步替身**，不是 drop-in replacement：
+
+- **没有 fiber / 子 context / scope**：插件拿到的是同一个 context，不是 Cordis fork 出来的子 context。
+- **没有依赖注入**：`inject`、`provide`、service、`reflect`、配置 schema 校验、logger 均未实现。
+- **effects 仅同步**：只接受「返回 cleanup 函数或 undefined/null」；Promise、async cleanup、iterator/async iterator 会抛 `TypeError`。
+- **不支持热重载**：没有 `ctx.update()`、`restart()`、`fiber.await()`、HMR 语义。
+- **事件能力有限**：没有 `once`、`prepend`、`parallel`/`serial`/`bail`/`waterfall`、事件过滤和 `internal/*` 生命周期事件。
+- **返回值是 mock 的便利约定**：`ctx.emit()` 返回 listener 返回值数组（Cordis 返回 void）；`ctx.plugin()` 返回 `ctx`（Cordis 返回 fiber 句柄）。
+- **listener 的 `this`**：本实现绑定为 `ctx`；这不是 Cordis 公开保证的一部分。
+- **单线程、无并发保护**：不要跨测试共享一个 context。
+- **不能证明真实资源已释放**：它只追踪通过 mock context 注册的 listener/effect/plugin；定时器、socket、文件句柄等需要插件自己的 cleanup 去释放，替身只能证明 cleanup 被调用了。
+
+如果测试需要真实的 Cordis 行为（fiber、inject、HMR），请用官方 `cordis` 运行时，而不是本包。
+
+## 命名核验
+
+核验日期：**2026-11-14**。结论：`cordis-testkit` 当时**未在 npm 注册**，也不是 Cordis 官方包名，但这是一个非保留名称，未来仍可能被他人占用；本包与官方无关联。
+
+证据与命令：
+
+```sh
+npm view cordis-testkit version
+# npm error 404 Not Found - GET https://registry.npmjs.org/cordis-testkit
+
+npm view cordis version
+# 4.0.0-rc.13   （cordiverse 官方包）
+
+npm view @cordisjs/testkit version
+npm view cordis-test-utils version
+npm view @cordisjs/test-utils version
+npm view cordis-mock version
+# 以上均 404（核验当日）
+```
+
+- 官方仓库：<https://github.com/cordiverse/cordis>；官方 npm 包名是 `cordis`，不是 `cordis-testkit`。
+- 官方仓库 `packages/` 目录（核验当日）为：`cli-cordis, cli, core, create, env, fs-node, fs, group, hmr, http-socks, http, include, loader, logger-console, package-manager, timer`，其中没有 `testkit`。
+- DeepSeek Harness 生态里另有 `@deepseek-ai/dsh-tool-testkit`、`@deepseek-ai/dsh-agent-loop-testkit` 等带 scope 的包，与本包无关；本包也不代表 DeepSeek。
+- 本项目只借用公开 API 形状做测试替身，不复用官方源码。官方 Cordis 为 MIT；本包为 Apache-2.0。
+
+如果上游未来发布同名/近似名包，应以官方命名为准，本包可随时更名。
+
+## 非官方声明
+
+本项目是社区独立项目，**不是 Cordis 官方实现**，也不由 cordiverse / Cordis
+作者或 DeepSeek 背书。`cordis`、`Cordis` 等名称属于其各自权利人；本包仅作为
+非官方的社区测试工具。Cordis 本身是 MIT 项目，本包使用 Apache-2.0。
+
+## License
+
+Apache-2.0，见 [LICENSE](./LICENSE)。
+
+`cordis`、`Cordis` 等名称属于其各自权利人。本包仅为非官方的社区测试工具。

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "cordis-testkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Unofficial mock Cordis context and effect-leak assertions for plugin unit tests.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": "./src/core.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "DESIGN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.9.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check": "node --check src/core.js"
+  },
+  "keywords": [
+    "cordis",
+    "testkit",
+    "mock-context",
+    "effect",
+    "leak-detection",
+    "unit-testing"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-next-suite.git",
+    "directory": "packages/cordis-testkit"
+  },
+  "homepage": "https://github.com/PerryLink/dsh-next-suite/tree/main/packages/cordis-testkit#readme",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-next-suite/issues"
+  },
+  "author": "PerryLink",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/core.js

@@ -0,0 +1,606 @@
+/**
+ * Unofficial, dependency-free test double for a Cordis context.
+ *
+ * This module is intentionally small: it records listeners, effects and
+ * plugins so plugin tests can (a) drive `ctx.emit()` deterministically and
+ * (b) fail when a plugin forgets to release something. It is **not** a
+ * Cordis runtime and does not implement fibers, dependency injection,
+ * service reflection or asynchronous effects. See README.md / DESIGN.md.
+ *
+ * @module cordis-testkit
+ */
+
+/**
+ * State slot. Registered with `Symbol.for` so several copies of this module
+ * can still recognise each other's contexts in a test process.
+ */
+const STATE = Symbol.for('cordis-testkit.state')
+
+/**
+ * @typedef {object} ListenerRecord
+ * @property {string | symbol} event
+ * @property {Function} callback
+ * @property {boolean} active
+ */
+
+/**
+ * @typedef {object} EffectRecord
+ * @property {string} label
+ * @property {boolean} active
+ * @property {boolean} disposed
+ * @property {(() => void) | null} cleanup
+ */
+
+/**
+ * @typedef {object} PluginRecord
+ * @property {string} name
+ * @property {boolean} active
+ * @property {boolean} disposed
+ * @property {(() => void) | null} cleanup
+ */
+
+/**
+ * LIFO cleanup entry. Listeners are removed en masse at the end of
+ * `dispose()`, so they do not need an entry here.
+ *
+ * @typedef {{ kind: 'effect', record: EffectRecord }
+ *   | { kind: 'plugin', record: PluginRecord }} CleanupEntry
+ */
+
+/**
+ * @typedef {object} MockContextState
+ * @property {ListenerRecord[]} listeners
+ * @property {EffectRecord[]} effects
+ * @property {PluginRecord[]} plugins
+ * @property {CleanupEntry[]} cleanups
+ * @property {Map<unknown, unknown>} store
+ * @property {boolean} disposed
+ * @property {number} sequence
+ */
+
+/**
+ * Active resources of a mock context, in registration order.
+ *
+ * @typedef {object} ContextSnapshot
+ * @property {(string | symbol)[]} listeners Active listener event names.
+ * @property {string[]} effects Active effect labels.
+ * @property {string[]} plugins Active plugin names.
+ * @property {boolean} disposed Whether `ctx.dispose()` has run.
+ */
+
+/**
+ * Read and validate internal state.
+ *
+ * @param {unknown} ctx
+ * @returns {MockContextState}
+ */
+function stateOf(ctx) {
+  const state =
+    ctx !== null && typeof ctx === 'object'
+      ? /** @type {Record<symbol, MockContextState | undefined>} */ (ctx)[STATE]
+      : undefined
+  if (!state) {
+    throw new TypeError(
+      'expected a mock context created by createMockContext()',
+    )
+  }
+  return state
+}
+
+/**
+ * @param {MockContextState} state
+ * @param {string} operation
+ */
+function assertActive(state, operation) {
+  if (state.disposed) {
+    throw new Error(`cannot ${operation} on a disposed Cordis mock context`)
+  }
+}
+
+/**
+ * @param {unknown} event
+ * @returns {asserts event is string | symbol}
+ */
+function assertEvent(event) {
+  if (typeof event !== 'string' && typeof event !== 'symbol') {
+    throw new TypeError('event must be a string or a symbol')
+  }
+}
+
+/**
+ * Resolve a plugin's display name and check that it is applicable.
+ *
+ * @param {unknown} plugin
+ * @param {MockContextState} state
+ * @returns {{ name: string, callback: Function, thisArg: unknown }}
+ */
+function normalizePlugin(plugin, state) {
+  if (typeof plugin === 'function') {
+    return {
+      name: plugin.name || `plugin#${++state.sequence}`,
+      callback: plugin,
+      thisArg: undefined,
+    }
+  }
+
+  if (
+    plugin !== null &&
+    typeof plugin === 'object' &&
+    typeof /** @type {{ apply?: unknown }} */ (plugin).apply === 'function'
+  ) {
+    const object = /** @type {{ name?: unknown, apply: Function }} */ (plugin)
+    let name = typeof object.name === 'string' ? object.name : ''
+    if (!name && object.apply.name && object.apply.name !== 'apply') {
+      name = object.apply.name
+    }
+    return {
+      name: name || `plugin#${++state.sequence}`,
+      callback: object.apply,
+      thisArg: object,
+    }
+  }
+
+  throw new TypeError(
+    'plugin must be a function or an object with an apply(ctx, config) method',
+  )
+}
+
+/**
+ * Dispose one effect and (optionally) collect its cleanup error.
+ *
+ * The record is marked disposed before the cleanup runs, so a re-entrant or
+ * repeated disposal cannot call the cleanup twice.
+ *
+ * @param {MockContextState} state
+ * @param {EffectRecord} record
+ * @param {unknown[] | null} errors Collect errors when non-null; otherwise
+ *   rethrow immediately (used by the disposer returned from `ctx.effect()`).
+ */
+function disposeEffect(state, record, errors) {
+  if (record.disposed) return
+  record.disposed = true
+  record.active = false
+
+  const index = state.effects.indexOf(record)
+  if (index !== -1) state.effects.splice(index, 1)
+
+  if (!record.cleanup) return
+  try {
+    record.cleanup()
+  } catch (error) {
+    if (errors) errors.push(error)
+    else throw error
+  }
+}
+
+/**
+ * Dispose one plugin instance and optionally collect its cleanup error.
+ *
+ * @param {MockContextState} state
+ * @param {PluginRecord} record
+ * @param {unknown[] | null} errors
+ */
+function disposePlugin(state, record, errors) {
+  if (record.disposed) return
+  record.disposed = true
+  record.active = false
+
+  const index = state.plugins.indexOf(record)
+  if (index !== -1) state.plugins.splice(index, 1)
+
+  if (!record.cleanup) return
+  try {
+    record.cleanup()
+  } catch (error) {
+    if (errors) errors.push(error)
+    else throw error
+  }
+}
+
+/**
+ * @param {unknown[]} names
+ * @returns {string}
+ */
+function formatNames(names) {
+  return names
+    .map((name) =>
+      typeof name === 'symbol' ? name.toString() : JSON.stringify(name),
+    )
+    .join(', ')
+}
+
+/**
+ * A minimal, synchronous mock of a Cordis context.
+ *
+ * Create one with {@link createMockContext}. Do not construct it directly in
+ * tests: `createMockContext()` is the stable entry point.
+ */
+export class MockContext {
+  constructor() {
+    /** @type {MockContextState} */
+    this[STATE] = {
+      listeners: [],
+      effects: [],
+      plugins: [],
+      cleanups: [],
+      store: new Map(),
+      disposed: false,
+      sequence: 0,
+    }
+  }
+
+  /** @returns {boolean} */
+  get disposed() {
+    return this[STATE].disposed
+  }
+
+  /**
+   * Register an event listener.
+   *
+   * The listener is invoked with the mock context as `this`. Registering the
+   * same callback twice creates two independent registrations.
+   *
+   * @param {string | symbol} event
+   * @param {(...args: unknown[]) => unknown} callback
+   * @returns {() => void} Idempotent disposer for this registration.
+   */
+  on(event, callback) {
+    const state = stateOf(this)
+    assertActive(state, 'register a listener')
+    assertEvent(event)
+    if (typeof callback !== 'function') {
+      throw new TypeError('listener must be a function')
+    }
+
+    /** @type {ListenerRecord} */
+    const record = { event, callback, active: true }
+    state.listeners.push(record)
+
+    let removed = false
+    return () => {
+      if (removed) return
+      removed = true
+      record.active = false
+      const index = state.listeners.indexOf(record)
+      if (index !== -1) state.listeners.splice(index, 1)
+    }
+  }
+
+  /**
+   * Emit an event synchronously.
+   *
+   * Listeners are snapshotted before dispatch: listeners added during the
+   * emit are not called by this emit, while listeners removed during it are
+   * skipped. Errors propagate and stop the dispatch, matching Cordis.
+   *
+   * Unlike Cordis (which returns `void`), this returns the listeners' return
+   * values as a convenience for tests.
+   *
+   * @param {string | symbol} event
+   * @param {...unknown} args
+   * @returns {unknown[]}
+   */
+  emit(event, ...args) {
+    const state = stateOf(this)
+    assertEvent(event)
+
+    const results = []
+    for (const record of state.listeners.slice()) {
+      if (!record.active || record.event !== event) continue
+      results.push(Reflect.apply(record.callback, this, args))
+    }
+    return results
+  }
+
+  /**
+   * Run a setup callback immediately and remember its cleanup.
+   *
+   * Supported return values are a synchronous cleanup function or
+   * `undefined`/`null`. Promises, iterators and other asynchronous forms are
+   * rejected: this test double is deliberately synchronous.
+   *
+   * Effects are considered owned resources even when they return no cleanup;
+   * `dispose()` or the returned disposer must be called before
+   * {@link assertNoLeaks} passes.
+   *
+   * @param {() => (() => void) | void | null} callback
+   * @param {string | symbol} [label] Diagnostic label; defaults to `effect#N`.
+   * @returns {() => void} Idempotent disposer for this effect.
+   */
+  effect(callback, label) {
+    const state = stateOf(this)
+    assertActive(state, 'register an effect')
+    if (typeof callback !== 'function') {
+      throw new TypeError('effect callback must be a function')
+    }
+
+    /** @type {EffectRecord} */
+    const record = {
+      label:
+        label === undefined || label === null
+          ? `effect#${++state.sequence}`
+          : String(label),
+      active: true,
+      disposed: false,
+      cleanup: null,
+    }
+    /** @type {CleanupEntry} */
+    const entry = { kind: 'effect', record }
+    state.effects.push(record)
+    state.cleanups.push(entry)
+
+    try {
+      const cleanup = callback()
+      if (cleanup !== undefined && cleanup !== null) {
+        if (typeof cleanup !== 'function') {
+          throw new TypeError(
+            'effect callback must return a synchronous cleanup function, ' +
+              'undefined or null',
+          )
+        }
+        record.cleanup = cleanup
+      }
+    } catch (error) {
+      // A failed setup must not leave a phantom effect behind.
+      record.active = false
+      record.disposed = true
+      const effectIndex = state.effects.indexOf(record)
+      if (effectIndex !== -1) state.effects.splice(effectIndex, 1)
+      const cleanupIndex = state.cleanups.indexOf(entry)
+      if (cleanupIndex !== -1) state.cleanups.splice(cleanupIndex, 1)
+      throw error
+    }
+
+    let removed = false
+    return () => {
+      if (removed) return
+      removed = true
+      disposeEffect(state, record, null)
+    }
+  }
+
+  /**
+   * Store a value on the mock context.
+   *
+   * @param {unknown} key
+   * @param {unknown} value
+   * @returns {unknown} The stored value.
+   */
+  set(key, value) {
+    stateOf(this).store.set(key, value)
+    return value
+  }
+
+  /**
+   * Read a value previously stored with {@link set}.
+   *
+   * @param {unknown} key
+   * @returns {unknown}
+   */
+  get(key) {
+    return stateOf(this).store.get(key)
+  }
+
+  /**
+   * Apply a plugin synchronously.
+   *
+   * Function plugins are called as `plugin(ctx, config)` with `this` bound to
+   * the mock context. Object plugins are called as `plugin.apply(ctx, config)`
+   * with `this` bound to the plugin object. A returned function is treated as
+   * the plugin's cleanup function and runs during `ctx.dispose()`.
+   *
+   * The plugin receives the same context (there is no forked child fiber),
+   * and its listeners/effects are therefore owned by this context.
+   *
+   * @param {Function | { name?: string, apply: Function }} plugin
+   * @param {unknown} [config]
+   * @returns {this} The context, for optional chaining.
+   */
+  plugin(plugin, config) {
+    const state = stateOf(this)
+    assertActive(state, 'load a plugin')
+    const target = normalizePlugin(plugin, state)
+
+    /** @type {PluginRecord} */
+    const record = {
+      name: target.name,
+      active: true,
+      disposed: false,
+      cleanup: null,
+    }
+    state.plugins.push(record)
+
+    let result
+    try {
+      result = Reflect.apply(target.callback, target.thisArg ?? this, [
+        this,
+        config,
+      ])
+    } catch (error) {
+      // The plugin never finished loading, so it has no instance to dispose.
+      record.active = false
+      const index = state.plugins.indexOf(record)
+      if (index !== -1) state.plugins.splice(index, 1)
+      throw error
+    }
+
+    if (result !== undefined && result !== null) {
+      if (typeof result !== 'function') {
+        record.active = false
+        record.disposed = true
+        const index = state.plugins.indexOf(record)
+        if (index !== -1) state.plugins.splice(index, 1)
+        throw new TypeError(
+          'plugin must return a synchronous cleanup function, ' +
+            'undefined or null',
+        )
+      }
+      record.cleanup = result
+    }
+
+    // Register the plugin's lifecycle after its apply completed, so cleanup
+    // runs before the effects it registered (LIFO disposal).
+    state.cleanups.push({ kind: 'plugin', record })
+    return this
+  }
+
+  /**
+   * Dispose the context.
+   *
+   * Cleanup entries (effects and plugin cleanups) run in reverse registration
+   * order; listener tables are cleared last. All cleanup errors are collected
+   * and rethrown together after every resource has been released, so a
+   * failing cleanup cannot leave the context half-alive.
+   *
+   * The call is idempotent: the second and later calls are no-ops, even if
+   * the first call threw. It is safe to call `dispose()` from inside a
+   * cleanup.
+   *
+   * @returns {void}
+   * @throws {AggregateError} When one or more cleanup functions threw.
+   */
+  dispose() {
+    const state = stateOf(this)
+    if (state.disposed) return
+    state.disposed = true
+
+    /** @type {unknown[]} */
+    const errors = []
+    while (state.cleanups.length > 0) {
+      const entry = /** @type {CleanupEntry} */ (state.cleanups.pop())
+      if (entry.kind === 'effect') {
+        disposeEffect(state, entry.record, errors)
+      } else {
+        disposePlugin(state, entry.record, errors)
+      }
+    }
+
+    for (const listener of state.listeners) listener.active = false
+    state.listeners.length = 0
+    state.effects.length = 0
+    state.plugins.length = 0
+
+    if (errors.length > 0) {
+      const error = new AggregateError(
+        errors,
+        `context disposal failed: ${errors.length} cleanup step(s) threw`,
+      )
+      // @ts-expect-error -- expando used by tests and tooling.
+      error.code = 'ERR_CORDIS_DISPOSE'
+      throw error
+    }
+  }
+}
+
+/**
+ * Create a fresh mock context.
+ *
+ * @returns {MockContext}
+ */
+export function createMockContext() {
+  return new MockContext()
+}
+
+/**
+ * Capture the context's active resources.
+ *
+ * The arrays are freshly allocated copies of the active resources (disposed
+ * registrations are omitted), so callers may mutate them freely.
+ *
+ * @param {MockContext} ctx
+ * @returns {ContextSnapshot}
+ */
+export function snapshot(ctx) {
+  const state = stateOf(ctx)
+  return {
+    listeners: state.listeners
+      .filter((listener) => listener.active)
+      .map((listener) => listener.event),
+    effects: state.effects
+      .filter((effect) => effect.active)
+      .map((effect) => effect.label),
+    plugins: state.plugins
+      .filter((plugin) => plugin.active)
+      .map((plugin) => plugin.name),
+    disposed: state.disposed,
+  }
+}
+
+/**
+ * Assert that the context has no active listeners, effects or plugins.
+ *
+ * Typical use is after `ctx.dispose()`:
+ *
+ * ```js
+ * const ctx = runPlugin(plugin)
+ * ctx.dispose()
+ * assertNoLeaks(ctx)
+ * ```
+ *
+ * A context that was never disposed still passes when every registration was
+ * explicitly released. `disposed` itself is not a requirement.
+ *
+ * @param {MockContext} ctx
+ * @returns {void}
+ * @throws {Error & { code: string, leaks: ContextSnapshot }} With a
+ *   human-readable inventory when resources remain.
+ */
+export function assertNoLeaks(ctx) {
+  const leaks = snapshot(ctx)
+  if (
+    leaks.listeners.length === 0 &&
+    leaks.effects.length === 0 &&
+    leaks.plugins.length === 0
+  ) {
+    return
+  }
+
+  const parts = []
+  if (leaks.listeners.length > 0) {
+    parts.push(
+      `listeners: ${leaks.listeners.length} [${formatNames(leaks.listeners)}]`,
+    )
+  }
+  if (leaks.effects.length > 0) {
+    parts.push(`effects: ${leaks.effects.length} [${formatNames(leaks.effects)}]`)
+  }
+  if (leaks.plugins.length > 0) {
+    parts.push(
+      `plugins: ${leaks.plugins.length} [${formatNames(leaks.plugins)}]`,
+    )
+  }
+
+  const error = new Error(
+    `Cordis mock context leak detected: ${parts.join('; ')}. ` +
+      'Call ctx.dispose() or release each registration before asserting.',
+  )
+  Object.assign(error, { code: 'ERR_CORDIS_LEAK', leaks })
+  throw error
+}
+
+/**
+ * Create a context, apply one plugin to it and return the live context.
+ *
+ * The caller owns disposal: call `ctx.dispose()` and then
+ * {@link assertNoLeaks} when the test is done. If applying the plugin throws,
+ * this helper disposes the partial context before rethrowing, so a failed
+ * setup cannot leak listeners/effects.
+ *
+ * @param {Function | { name?: string, apply: Function }} plugin
+ * @param {unknown} [config]
+ * @returns {MockContext}
+ */
+export function runPlugin(plugin, config) {
+  const ctx = createMockContext()
+  try {
+    ctx.plugin(plugin, config)
+  } catch (error) {
+    try {
+      ctx.dispose()
+    } catch {
+      // Preserve the plugin's original error; cleanup errors are secondary.
+    }
+    throw error
+  }
+  return ctx
+}