test(database): verify real plugin request cancellation

docs/guides/database-validation.md

@@ -1,6 +1,6 @@
 # Database service acceptance
 
-This record separates public-module service/failure checks from positive workflows through actual plugin DSOs. Each scope has its own tested revisions and environment; a passing result applies only to that scope.
+This record separates public-module service/failure checks, positive workflows through actual plugin DSOs, and server-observed request cancellation through those DSOs. Each scope has its own tested revisions and environment; a passing result applies only to that scope.
 
 ## Public modules against real services
 
@@ -60,6 +60,40 @@ cmake --build database-build --target ark_database_public_plugin_service_tests -
 
 These are standalone C++ test modes. They do not create or stop services; missing configuration or an unavailable protocol fails rather than becoming a successful skip. `check-database` builds this program and its DSOs without running the real-service modes.
 
+## Real plugin request cancellation
+
+Both modes of `ark_database_public_plugin_cancellation_tests` passed on **2026-10-26**, each with exit code `0`. The host uses only public interfaces and loads the actual hidden-symbol database plugin DSOs.
+
+| Environment | Value |
+| --- | --- |
+| Machine | Mac16,11 · Apple M4 Pro · 14 cores · 48 GiB |
+| System | macOS 27.0.1 (26A434) · arm64 |
+| Build | Apple Clang 21.0.0 · C++20 · Boost.Asio · Debug · SSL enabled · OpenSSL 3.6.4 |
+| Executed ark | `dba34762dd58348784e46a2518f7505e52063d55` |
+| arknet | CI pin `a0dfe09cd543e75cfb5996e537ce2fa49f2a758f` |
+| Services | Redis 7.4.2 over authenticated TCP; MySQL Community Server 8.4.13 with required verified TLS |
+
+Cancellation is requested through the existing `task_group::cancel(id)` only after an independent pool observes the uniquely identified operation on the server. Polling timers only throttle observations; elapsed time is not the active-operation barrier.
+
+| Mode | Server observation before cancellation | Original native result and observed effect |
+| --- | --- | --- |
+| `redis` | `CLIENT LIST` identified the named pipeline blocked in BLPOP after its preceding INCR counter became `1` | `client_errc::cancelled`, `command_may_have_run=true`, no transport error and retained integer partial reply `1`. Explicit PING recovered; the observed block retired and the exclusive counter remained `1`. |
+| `mysql` | `PROCESSLIST` identified the tagged UPDATE in `User sleep` | `connection_errc::cancelled`, `outcome_unknown=true` and `operation_aborted` transport status. An explicit query recovered; the observer waited for the tagged statement to disappear across all states and a bounded quiet window before reading the final counter, which was `1`. |
+
+The cancelled values remain service results, not coroutine exceptions. Request and observer roots each complete once on the owner thread/shared executor. Repeated cancellation of a pending task is accepted; its retired ID rejects cancellation. Both controlled tests complete natural managed/native shutdown within their observation and pumping bounds; repeated stop succeeds, and owning cancelled results remain readable after plugin/module/manager/runtime destruction. These are test guards, not a hard or preemptive production deadline: `manager.stop()` remains cooperative and cannot interrupt blocking hooks. No production timeout or cancellation policy is added, and `cancel_all` or forced frame destruction is not used for teardown.
+
+The final counters describe only the observed operations and finite observation window. The MySQL case permits `0` or `1` while the outcome is unknown; this run observed `1`. Cancellation does not establish rollback, global exactly-once execution or every possible retry race.
+
+Use the [standalone C++ cancellation guide](../../tests/database/cancellation.md) to prepare exclusively owned services, private authentication and the required database privileges. These modes write exclusive Redis keys or a private MySQL counter table; do not use shared services. With the SSL-enabled database build configured:
+
+```sh
+cmake --build database-build --target ark_database_public_plugin_cancellation_tests --parallel 1
+./database-build/tests/database/ark_database_public_plugin_cancellation_tests redis
+./database-build/tests/database/ark_database_public_plugin_cancellation_tests mysql
+```
+
+`check-database` compiles the program without running the real-service modes. Both owned servers were shut down normally using authenticated commands; the exact processes were independently confirmed absent and private data, credentials and TLS keys were removed. Server termination was not a test action.
+
 ## Acceptance boundaries
 
-The DSO workflows exercise normal plugin teardown and native close calls. Successful `FreeLibrary` or `dlclose` does not prove that the operating system physically removed the library image. Request cancellation, server termination, OS image removal, other deployment environments and cross-machine capacity still require separate acceptance. Neither test scope establishes arbitrary hot-update safety or production capacity.
+The DSO workflows exercise normal plugin teardown and native close calls. Successful `FreeLibrary` or `dlclose` does not prove that the operating system physically removed the library image. Request cancellation acceptance is limited to the selected server-observed operations on this host. Transaction cancellation, Redis TLS, other cancellation/retry races, server termination, OS image removal, other platforms/deployment environments and cross-machine capacity remain unverified. These records do not establish arbitrary hot-update safety or production capacity.

docs/guides/database-validation_CN.md

@@ -1,6 +1,6 @@
 # 数据库服务验收
 
-本页分别记录公开模块的真实服务正常／故障检查，以及通过真实插件 DSO 执行的正常流程。每类检查保留各自的测试版本与环境；通过结果仅适用于对应范围。
+本页分别记录公开模块的真实服务正常／故障检查、真实插件 DSO 正常流程，以及经服务端观察确认的 DSO 请求取消。每类检查保留各自的测试版本与环境；通过结果仅适用于对应范围。
 
 ## 公开模块与真实服务
 
@@ -60,6 +60,40 @@ cmake --build database-build --target ark_database_public_plugin_service_tests -
 
 这些模式由独立 C++ 程序执行，不创建或停止服务。缺少配置、构建中没有所选协议时，程序返回失败，不会跳过并报告成功。`check-database` 仅构建该程序及其 DSO，不运行真实服务模式。
 
+## 真实插件请求取消
+
+**2026-10-26**，`ark_database_public_plugin_cancellation_tests` 的两种模式均通过，退出码均为 `0`。宿主仅使用公开接口，加载真实的隐藏符号数据库插件 DSO。
+
+| 环境 | 配置 |
+| --- | --- |
+| 机器 | Mac16,11 · Apple M4 Pro · 14 核 · 48 GiB |
+| 系统 | macOS 27.0.1（26A434）· arm64 |
+| 构建 | Apple Clang 21.0.0 · C++20 · Boost.Asio · Debug · 启用 SSL · OpenSSL 3.6.4 |
+| 实际执行的 ark | `dba34762dd58348784e46a2518f7505e52063d55` |
+| arknet | CI 固定版本 `a0dfe09cd543e75cfb5996e537ce2fa49f2a758f` |
+| 服务 | Redis 7.4.2：TCP 与密码认证；MySQL Community Server 8.4.13：强制 TLS 与证书校验 |
+
+独立连接池先在服务端观察到唯一标识的操作，再通过现有 `task_group::cancel(id)` 请求取消。定时器仅降低轮询频率，等待时间不能替代操作已在服务端运行的证据。
+
+| 模式 | 取消前的服务端观察 | 原生结果与实际影响 |
+| --- | --- | --- |
+| `redis` | `CLIENT LIST` 确认具名流水线在 BLPOP 中阻塞，此前的 INCR 已使计数变为 `1` | 保留 `client_errc::cancelled`、`command_may_have_run=true`、无传输错误与整数部分回复 `1`。显式 PING 恢复成功；观察到的阻塞命令退出后，独占计数仍为 `1`。 |
+| `mysql` | `PROCESSLIST` 确认带标记的 UPDATE 处于 `User sleep` | 保留 `connection_errc::cancelled`、`outcome_unknown=true` 与 `operation_aborted` 传输状态。显式新查询恢复成功；观察者确认该语句在所有状态下均已消失，并经过有限静默观察期后，读取最终计数，本次为 `1`。 |
+
+取消值仍作为服务结果返回，不转换为协程异常。请求与观察根任务分别在所属线程／共享执行器完成一次。重复取消尚未退出的任务会被接收，取消已退出 ID 则失败。两个受控测试均在各自的观察与驱动时限内完成托管任务和原生资源的自然停机，重复 stop 成功；插件／模块／管理器／运行时销毁后，拥有型取消结果仍可读取。这些时限仅用于测试，不构成强制或抢占式生产期限：`manager.stop()` 仍为协作式调用，不能中断阻塞中的钩子。本次不增加生产超时或取消策略，停机不使用 `cancel_all` 或强制销毁协程帧。
+
+最终计数仅描述本次观察到的操作及有限观察窗口。MySQL 用例在结果未知时允许 `0` 或 `1`，本次观察到 `1`。取消不证明回滚、全局恰好执行一次，也不覆盖全部重试竞争。
+
+按[独立 C++ 取消验收指南](../../tests/database/cancellation_CN.md)准备独占服务、私有认证配置与数据库权限。这些模式会写入独占 Redis 键或私有 MySQL 计数表，不应对共享服务运行。完成启用 SSL 的数据库构建配置后，执行：
+
+```sh
+cmake --build database-build --target ark_database_public_plugin_cancellation_tests --parallel 1
+./database-build/tests/database/ark_database_public_plugin_cancellation_tests redis
+./database-build/tests/database/ark_database_public_plugin_cancellation_tests mysql
+```
+
+`check-database` 仅编译该程序，不运行真实服务模式。两个自有服务均通过认证命令正常关闭；精确进程已独立确认不存在，私有数据、凭据与 TLS 密钥已删除。服务端终止不是本次测试动作。
+
 ## 验收边界
 
-DSO 流程覆盖正常插件销毁与原生关闭调用。`FreeLibrary` 或 `dlclose` 成功不证明操作系统已物理移除库映像。请求取消、服务端终止、操作系统库映像移除、其他部署环境与跨机器容量仍需单独验收。这两类检查均不证明任意热更新安全或生产容量。
+DSO 流程覆盖正常插件销毁与原生关闭调用。`FreeLibrary` 或 `dlclose` 成功不证明操作系统已物理移除库映像。本机请求取消验收仅覆盖记录中经服务端观察确认的操作。事务取消、Redis TLS、其他取消／重试竞争、服务端终止、操作系统库映像移除、其他平台／部署环境与跨机器容量仍未验收。这些记录均不证明任意热更新安全或生产容量。

docs/project/roadmap.md

@@ -8,13 +8,13 @@ This page distinguishes supported source behavior from remaining design and depl
 - Public [MySQL](../reference/mysql.md) and [Redis](../reference/redis.md) modules use arknet native clients through Asio coroutine entry points. Inputs and results own their storage; manager-owned task groups resume on the module owner thread. MySQL includes prepared statements and transactions; Redis includes commands and pipelines. Legacy database drivers are no longer the public plugin interface.
 - Startup callbacks propagate the first failure. The launcher reports the failed phase and exits with code `1` before the update loop. Shutdown stops managed task admission, drains accepted tasks and waits for module readiness. A configured cooperative wait timeout retains the process/resources and disables unloading. These behaviors do not provide partial-startup rollback or a hard process-stop deadline. See [application startup and shutdown](../guides/applications.md) and [managed tasks](../guides/tasks.md).
 
-Public database service/failure checks and the [real-plugin DSO positive workflows](../guides/database-validation.md#real-plugin-dsos-against-real-services) passed against isolated Redis and MySQL servers on macOS. The [database service acceptance record](../guides/database-validation.md) keeps their distinct tested revisions, environments and scope; those results do not cover every deployment or source revision.
+Public database service/failure checks, [real-plugin DSO positive workflows](../guides/database-validation.md#real-plugin-dsos-against-real-services) and [bounded server-observed request cancellation](../guides/database-validation.md#real-plugin-request-cancellation) passed against isolated Redis and MySQL servers on macOS. The [database service acceptance record](../guides/database-validation.md) keeps their distinct tested revisions, environments and scope; those results do not cover every deployment or source revision.
 
 ## Remaining acceptance and design
 
 | Area | Remaining work and acceptance boundary |
 | --- | --- |
-| Database deployment | Run separate real-service acceptance for request cancellation, server termination and OS library-image removal. Add target-environment and cross-machine capacity evidence before making deployment or capacity claims. Local protocol endpoints and construction checks do not replace these runs. |
+| Database deployment | Transaction cancellation, Redis TLS, other cancellation/retry races, server termination, other platforms and OS library image removal still need acceptance. Add target-environment and cross-machine capacity evidence before making deployment or capacity claims. Local protocol endpoints and construction checks do not replace these runs. |
 | Startup and shutdown | Partial-startup rollback is not provided. A common dependency-aware shutdown protocol remains design work; managed task drain alone does not prove that arbitrary callbacks, native workers or background cleanup have ended. Define ownership and admission phases before extending unload guarantees. |
 | Optional plugins | Kafka construction/export checks do not test broker delivery, flush behavior or service interoperability; its driver build needs independent platform acceptance. OSS SDK remains a scaffold without client/request functionality. Physic retains the explicit unsupported legacy PhysX 3 configuration failure. See [optional plugin boundaries](../reference/directory-structure.md). |
 | C++20 modernization | Review each remaining module and optional integration against its own API, build and runtime requirements. The language baseline, header layout and focused construction checks do not establish completion of the whole modernization. |

docs/project/roadmap_CN.md

@@ -8,13 +8,13 @@
 - 公开 [MySQL](../reference/mysql_CN.md) 与 [Redis](../reference/redis_CN.md) 模块通过 Asio 协程入口使用 arknet 原生客户端。输入与结果拥有自身存储；管理器拥有的任务组在模块所属线程恢复。MySQL 提供预处理语句与事务，Redis 提供命令与流水线。旧数据库驱动已不再作为公开插件接口。
 - 启动回调的首个失败会向上传递。启动器报告失败阶段，在进入更新循环前以退出码 `1` 终止。停止时关闭托管任务接收，排空已接收任务并等待模块就绪。配置的协作式等待超时会保留进程和资源，并禁止卸载。这些行为不提供部分启动回滚，也不构成强制进程退出期限。见[应用启动与停止](../guides/applications_CN.md)和[托管任务](../guides/tasks_CN.md)。
 
-公开数据库接口的正常／故障检查，以及[真实插件 DSO 正常流程](../guides/database-validation_CN.md#真实插件动态库与真实服务)，已在 macOS 上通过隔离 Redis 与 MySQL 真实服务验收。[数据库服务验收记录](../guides/database-validation_CN.md)分别保留各自的测试版本、环境与范围；这些结果不覆盖所有部署环境或源码版本。
+公开数据库接口的正常／故障检查、[真实插件 DSO 正常流程](../guides/database-validation_CN.md#真实插件动态库与真实服务)，以及[经服务端观察确认的有界请求取消](../guides/database-validation_CN.md#真实插件请求取消)，已在 macOS 上通过隔离 Redis 与 MySQL 真实服务验收。[数据库服务验收记录](../guides/database-validation_CN.md)分别保留各自的测试版本、环境与范围；这些结果不覆盖所有部署环境或源码版本。
 
 ## 剩余验收与设计
 
 | 领域 | 剩余工作与验收边界 |
 | --- | --- |
-| 数据库部署 | 为请求取消、服务端终止和操作系统库映像移除分别执行真实服务验收。发布部署或容量结论前，补充目标环境与跨机器容量证据。本机协议端点与构造检查不能替代这些验收。 |
+| 数据库部署 | 事务取消、Redis TLS、其他取消／重试竞争、服务端终止、其他平台与操作系统库映像移除仍需验收。发布部署或容量结论前，补充目标环境与跨机器容量证据。本机协议端点与构造检查不能替代这些验收。 |
 | 启动与停机 | 框架不提供部分启动回滚。通用的依赖感知停机协议仍需设计；托管任务排空不代表任意回调、原生工作线程或后台清理均已结束。扩展卸载保证前，先明确所有权与接收阶段。 |
 | 可选插件 | Kafka 构造／导出检查不验证 broker 投递、flush 行为或服务互通；驱动构建仍需独立平台验收。OSS SDK 保持骨架状态，不提供客户端／请求功能。Physic 保留旧版 PhysX 3 不受支持的显式配置失败。见[可选插件边界](../reference/directory-structure_CN.md)。 |
 | C++20 改造 | 按各模块与可选集成的 API、构建和运行要求继续审查。语言基线、头文件布局和局部构造检查不足以证明全部改造完成。 |

tests/database/CMakeLists.txt

@@ -63,6 +63,13 @@ set_property(TARGET ark_database_public_plugin_service_tests PROPERTY LINK_LIBRA
 target_compile_definitions(ark_database_public_plugin_service_tests PRIVATE
     ARK_DATABASE_PLUGIN_DIR="$<TARGET_FILE_DIR:ark_database_redis_plugin>/")
 add_dependencies(ark_database_public_plugin_service_tests ark_database_redis_plugin)
+# Explicit real-service cancellation; compile in CI, execute only against owned services.
+ark_database_test(ark_database_public_plugin_cancellation_tests public_plugin_cancellation.cpp)
+set_property(TARGET ark_database_public_plugin_cancellation_tests PROPERTY INCLUDE_DIRECTORIES "")
+set_property(TARGET ark_database_public_plugin_cancellation_tests PROPERTY LINK_LIBRARIES ark::redis Threads::Threads)
+target_compile_definitions(ark_database_public_plugin_cancellation_tests PRIVATE
+    ARK_DATABASE_PLUGIN_DIR="$<TARGET_FILE_DIR:ark_database_redis_plugin>/")
+add_dependencies(ark_database_public_plugin_cancellation_tests ark_database_redis_plugin)
 # Compile and load each sample's real module and plugin assembly with a local
 # provider that rejects configuration before coroutine or network work.
 function(ark_database_sample_check database)
@@ -108,7 +115,8 @@ add_custom_target(check-database
 
 # Compile real-service acceptance in ordinary CI without running any server work.
 add_dependencies(check-database ark_database_redis_sample_check ark_database_public_service_tests
-    ark_database_public_failure_service_tests ark_database_public_plugin_service_tests check-database-samples)
+    ark_database_public_failure_service_tests ark_database_public_plugin_service_tests
+    ark_database_public_plugin_cancellation_tests check-database-samples)
 
 if(ARKNET_ENABLE_SSL)
     target_link_libraries(ark_database_public_failure_service_tests PRIVATE ark::mysql)
@@ -140,6 +148,8 @@ if(ARKNET_ENABLE_SSL)
     add_dependencies(ark_database_public_mysql_plugin_tests ark_database_mysql_plugin)
     add_dependencies(ark_database_public_plugin_service_tests ark_database_mysql_plugin)
     target_link_libraries(ark_database_public_plugin_service_tests PRIVATE ark::mysql)
+    target_link_libraries(ark_database_public_plugin_cancellation_tests PRIVATE ark::mysql)
+    add_dependencies(ark_database_public_plugin_cancellation_tests ark_database_mysql_plugin)
     ark_database_sample_check(mysql)
     add_custom_target(check-database-samples-mysql
         COMMAND $<TARGET_FILE:ark_database_mysql_sample_tests>