@zq-silk/yui 2.12.0 → 2.15.0

package/docs/testing/verification-levels.md

@@ -50,12 +50,15 @@ is required.
 ## Permanent core smoke
 
 `npm test` and `npm run test:core` build the checkout and run the maintained suite.
-The stable suite owns current storage 1.20 and its declared 1.0 through 1.19 minor
+Both include `test/core` and `test/platform`. For an already built checkout,
+`npm run test:business` runs only `test/core` and `npm run test:platform` runs
+only `test/platform`; neither rebuilds. CI owns one explicit build per job.
+The stable suite owns current storage 1.21 and its declared 1.0 through 1.20 minor
 transition. It contains no undeclared historical format compatibility path.
 
 Current coverage includes:
 
-1. Fresh storage 1.20, exact schema/record validation, no initialization over
+1. Fresh storage 1.21, exact schema/record validation, no initialization over
    unknown data, and rejection of old integer formats without mutation.
 2. Exact-version staging, mismatched-target refusal, same-major contiguous
    minor preflight, explicit maintenance-owner identity across handover, and
@@ -112,11 +115,20 @@ adjudication aggregation are deterministic; they do not run or measure a model.
 
 ## CI and release
 
-`ci.yml` runs core plus one assembled-package normal-path smoke per supported
-platform (Linux x64, Mac Intel and Apple Silicon) on every PR, without another
-lint or broad regression suite.
-Linux runs on Node 24 and 26; release fresh-install smoke covers Node 20, 22,
-24 and 26 on all three platforms.
+`ci.yml` runs on PRs and master. Business contracts and full package business
+wiring run once on Linux x64/Node 24. Platform tests run on Linux Node 24/26
+and Mac Intel/Apple Silicon Node 24. Every job builds exactly once, without
+another lint or implicit pretest build. Keep the existing job names for branch
+checks; the complete workflow must pass for the exact master commit.
+
+| Evidence | PR/master | Exact release tarball |
+| --- | --- | --- |
+| Business/state/authority contracts (`test/core`) | Linux 24 once | Reuse exact-SHA successful Core CI |
+| OS/helper/PTY/Git/SQLite boundaries (`test/platform`) | Linux 24/26, both Macs 24 | Real SQLite SQL/GC on all 12 installs; other installed boundaries below |
+| `full` smoke: business Jobs/Schedules + lifecycle + compatibility | Linux 24 once | Reuse exact-SHA business evidence |
+| `lifecycle` smoke: restart, Session/Host handoff, archive + compatibility | Both Macs 24 (Linux included in full) | Node 24 on each of the 3 platforms |
+| `compatibility` smoke: setup, CLI/bin, helpers, Doctor/PTY/SQLite | Linux 26 (included in other profiles) | All 3 platforms × Node 20/22/24/26 (included in lifecycle on 24) |
+
 `node scripts/smoke-runtime-package.mjs --assembled .release-stage` exercises
 the actual CLI/Controller/Host/SQLite and isolated tmux, replacing only the
 external Provider with a deterministic fixture. It covers setup, durable input
@@ -127,20 +139,65 @@ and grouped viewers without affecting a similarly named neighboring session.
 The fixture owns a fresh Home and its PATH, installs cleanup before setup,
 and never calls an installed model Agent.
 
+The default `full` profile also checks public Jobs, both service Schedule targets,
+real local Project fast-forward, Task delegation and Agent Job routing. Project
+sync supplies the real `existing-job` dispatch; one explicit `new-job` Schedule
+supplies the other path, without another existing-job no-op scenario. These are
+business wiring, not an ABI matrix.
+
+Keep mutations and final externally observable assertions on the real CLI.
+Readiness polls may read exact fixture-owned Run/Task IDs and events through the
+installed package's read-only Store, then confirm success through the CLI. Such
+observers cannot mutate state, drive reconciliation, replace authority/CLI-output
+checks, or turn missing records into success. Connections close after each read.
+Controller handover keeps its coherent session-context/backlog snapshot.
+
+Avoid paying for the same assertion at several layers:
+
+| Redundant work | Surviving coverage |
+| --- | --- |
+| Extra existing-job no-op Schedule | Real Project-sync Schedule → runner → Git fast-forward; Schedule rules/authority in `test/core/schedule.test.js` |
+| Artifact preview/list and repeated Run-result projection | Package artifact save → pinned read; projection/version/isolation assertions in `test/core/job-artifact.test.js` |
+| Cancel and re-query already-terminal Jobs during cleanup | Actual active Runs still cancelled and awaited; Task-delegation cancellation remains exercised |
+| Re-reading an original in both fake Provider handlers; unused Task Job evidence read | One original read feeds both handlers; exact Global delivery or Task wake acceptance, claim/report/ACK still use CLI |
+
+All Agent Job target routes, reuse/replacement, exact inbox identities, negative
+authority checks and native process custody remain real package smoke scenarios.
+Do not delete a distinct wiring path merely because a component test has a
+similar name, or add a second permanent suite for observer helpers.
+
+Smoke logs report each phase's wall time and the parent harness's `runCli`
+call count/time. CLI time includes command execution and Controller waits,
+is already inside phase time, and excludes CLI calls launched by fake Providers
+or other helpers. It is not a pure startup benchmark or an additional duration.
+Notification polling retains a newly observed exact wake ID while refreshing
+terminal events; historical wake details are not repeatedly expanded.
+
+Installation, version/help and first setup run without a compile cache. After
+setup, `full` and `lifecycle` give repeated real CLI processes a fixture-local
+`NODE_COMPILE_CACHE`; `compatibility` stays uncached throughout. This is Node's
+compiled-JavaScript cache, not cached results, native binaries or Home state.
+It starts empty on each smoke invocation and is removed with the fixture.
+No cache is restored across jobs, packages or Node versions, and no production
+default changes. Keep it out of V8 coverage runs, where it can reduce precision.
+
 `publish.yml` builds one archive containing all three native targets and runs
-the same smoke on each platform and supported Node version against that exact
-freshly installed package through
+the profiles above against that exact freshly installed package through
 `YUI_INSTALLED_ROOT`, adding actual npm-bin, dependency, supported Node version,
 artifact and provenance boundaries. This validates runtime integration, not
 real-model behavior. Pure contract and safety tests remain in `test/core`;
 production wiring is exercised here rather than only through mocked ports.
-The same release matrix runs `test/core/sqlite-driver.test.js` against the
-installed consumer: native selection boundaries plus real SQL, transactions,
+The same release matrix runs `test/platform/sqlite-native.test.js` against the
+installed consumer: selected-driver allocation/GC plus real SQL, transactions,
 JSON/RETURNING, WAL and backup for each usable optional SQLite candidate.
 An unavailable optional candidate is explicitly skipped, not reported as
 compatible; the normal selected-driver path must still pass. Doctor smoke
 reports the selected driver, engine and fallback reason. This matrix does not
 prove old-glibc compatibility.
+Pure selector/classification branches remain in `test/core/sqlite-driver.test.js`
+and run once. Do not duplicate native PTY/SQL probes immediately before the same
+installed Doctor/native-SQL checks; the repository dependency cache is still
+verified after building. Never reuse a consumer's native binaries across ABIs.
 The native dependency check launches a fixed local program through PTY and
 requires its output and normal exit. Installed-package smoke explicitly checks
 default Doctor's PTY results using dependencies resolved from the consumer.
@@ -161,6 +218,15 @@ current-contract process-handover regression, not proof of compatibility with
 every historical Host build. These checks have no installation or publication
 effect.
 
+Smoke logs report `TIMING` phases and total, including cleanup. Measure source
+build, dependency installation/cache restore, pure test time and npm install
+separately. Actions elapsed time includes queue and re-runs; report those
+separately instead of treating workflow wall time as test execution time.
+Existing npm/native caches and the exact-tarball checksum/provenance gates remain
+unchanged. Registry installation, release-asset byte comparison and updater
+verification attest different boundaries; do not remove them as “duplicate”
+without equivalent identity-bound evidence.
+
 Configured Agents acting as developers or reviewers are ordinary execution
 resources. Using a live provider or model as the subject of validation is
 different: paid APIs, shared Homes, production systems, real account quota, and

package/docs/testing/verification-levels.zh-CN.md

@@ -36,12 +36,15 @@ Yui 是一个单用户本地产品。永久验证保护关键的 happy path 和
 ## 永久 core smoke
 
 `npm test` 和 `npm run test:core` 构建当前 checkout 并运行维护中的套件。
-稳定套件维护当前存储 1.20 和明确声明的 1.0 至 1.19 连续小版本迁移，
+两者均包含 `test/core` 和 `test/platform`。已构建的 checkout 可分别运行
+`npm run test:business` 与 `npm run test:platform`，它们不会再次构建。
+CI 每个作业只显式构建一次。
+稳定套件维护当前存储 1.21 和明确声明的 1.0 至 1.20 连续小版本迁移，
 不包含未声明的历史格式兼容路径。
 
 当前覆盖包括：
 
-1. 新建存储 1.20、精确结构与记录校验、禁止覆盖未知数据库、无修改拒绝旧整数格式。
+1. 新建存储 1.21、精确结构与记录校验、禁止覆盖未知数据库、无修改拒绝旧整数格式。
 2. 精确版本暂存、目标不匹配拒绝、同主版本连续小版本预检、交接锁显式所有者，
    以及恢复时核对捕获的协议和存储身份，不接受缺失字段。
 3. 持久 Task／Message／Decision 上下文、Draft 激活权威、mailbox 认领、
@@ -78,10 +81,19 @@ package-start 检查跟随已安装树中的本地 Skill 引用，包括跨 Role
 
 ## CI 与发布
 
-`ci.yml` 在每个 PR 上构建一次，运行 core 及一个组装包正常链路检查，不重复 lint，
-也不增加宽泛回归套件。
-Linux CI 在 Node 24 和 26 上运行；发布时的全新安装 smoke 覆盖三个平台上的
-Node 20、22、24 和 26。
+`ci.yml` 在 PR 和 master 上执行。业务契约与完整业务链路仅在 Linux x64/Node 24
+运行一次；平台测试在 Linux Node 24/26、Intel/Apple Silicon Mac Node 24 上运行。
+每个作业只构建一次，不重复 lint 或隐含 pretest 构建。保留现有作业名称；发布仍要求
+精确 master SHA 的整个 Core CI 成功，不复用另一源码的结果。
+
+| 证据 | PR/master | 精确发布 tarball |
+| --- | --- | --- |
+| 业务、状态、授权契约（`test/core`） | Linux 24 一次 | 复用精确 SHA 的成功 Core CI |
+| OS/helper/PTY/Git/SQLite（`test/platform`） | Linux 24/26、双 Mac 24 | 12 组真实 SQL/GC；其余安装边界见下 |
+| `full`：Jobs/Schedules 业务链路 + lifecycle + compatibility | Linux 24 一次 | 复用精确 SHA 业务证据 |
+| `lifecycle`：重启、Session/Host 交接、归档 + compatibility | 双 Mac 24，Linux 已在 full 内 | 三平台 Node 24 |
+| `compatibility`：setup、CLI/bin、helper、Doctor/PTY/SQLite | Linux 26，其余已包含 | 三平台 × Node 20/22/24/26，24 已包含在 lifecycle 内 |
+
 `node scripts/smoke-runtime-package.mjs --assembled .release-stage` 经过真实
 CLI/Controller/Host/SQLite 与隔离 tmux，仅用确定性夹具替换外部 Provider。它验证
 setup、输入跨重启持久化及幂等、scratch 激活、原生结果入库、完成后保留会话、
@@ -89,14 +101,51 @@ setup、输入跨重启持久化及幂等、scratch 激活、原生结果入库
 归档释放活/死 pane 和附属查看 session，且不影响相似名称的相邻 session。
 夹具拥有新建 Home 和独立 PATH，在 setup 前建立清理责任，不调用安装的真实模型 Agent。
 
-`publish.yml` 通过 `YUI_INSTALLED_ROOT` 对刚安装的包执行同一个 smoke，增加真实
+默认 `full` 还覆盖公共 Job、两种 service Schedule 目标、本地 Project 快进、
+Task 委派和 Agent Job 路由。Project sync 已验证真实 `existing-job` 调度，
+另外保留一条显式 `new-job` Schedule，不再额外跑一条 existing-job 空操作。
+这些是业务组装证据，不是 ABI 矩阵。
+
+操作和最终外部可见结果仍通过真实 CLI 验证。就绪轮询可以用安装包的只读 Store
+观察夹具自己的准确 Run／Task ID 和事件，再通过 CLI 确认成功。观察器不能写状态、
+驱动 reconcile、替代权限或 CLI 输出契约检查，也不能把记录缺失当作成功；
+每次读取后关闭连接。Controller 接管仍使用一致的 Session Context／backlog 快照。
+
+避免同一断言在多个层次重复付费：
+
+| 删除的重复工作 | 保留的覆盖 |
+| --- | --- |
+| 额外 existing-job 空操作 Schedule | 真实 Project-sync 调度→runner→Git 快进；`test/core/schedule.test.js` 的规则和权限断言 |
+| Artifact 预览／列表及重复 Run-result 投影 | 安装包保存→固定版本读取；`test/core/job-artifact.test.js` 的投影、版本和隔离断言 |
+| 清理时对已终结 Job 再取消并查询 | 仍取消并等待真正活动的 Run；保留 Task 委派取消验证 |
+| 假 Provider 两个处理器重复读取原文；Task Job 未使用的 evidence 查询 | 一次原文读取供两个处理器使用；Global delivery 或 Task wake 的准确接收证据以及 claim/report/ACK 仍走 CLI |
+
+Agent Job 各目标接线、复用／替换、准确 inbox 身份、权限拒绝和原生进程归属继续通过
+真实安装包验证。不能因为组件测试名称相似就删除不同接线路径，也不为观察器辅助函数
+另建一套长期测试矩阵。
+
+冒烟日志分别报告每阶段实际耗时，以及父测试脚本 `runCli` 的调用次数和累计耗时。
+CLI 耗时包含命令执行与 Controller 等待，已计入阶段总时间；不含假 Provider 或
+其他 helper 发起的 CLI 调用，不能解释为纯启动耗时，也不能再次加到总时间上。
+通知轮询找到新通知后保留其准确 wake ID，并持续刷新终态事件，不反复展开历史通知详情。
+
+安装、version/help 和首次 setup 不使用编译缓存。setup 后，`full` 和 `lifecycle`
+为重复的真实 CLI 进程设置夹具内的 `NODE_COMPILE_CACHE`；`compatibility` 全程不启用。
+它只复用 Node 编译的 JavaScript，不缓存命令结果、原生二进制或 Home 状态。
+每次 smoke 都从空缓存开始，随夹具一起删除；不跨作业、安装包或 Node 版本恢复，
+也不改变产品默认行为。V8 覆盖率采集不要启用该缓存，以免降低统计精度。
+
+`publish.yml` 通过 `YUI_INSTALLED_ROOT` 对刚安装的包执行上表 profile，增加真实
 npm bin、依赖、受支持 Node 版本、产物和 provenance 边界。这证明运行时集成，不证明
 真实模型行为。纯契约与安全检查保留在 `test/core`，生产组件组装在这里验证，
 不只依赖模拟端口。
-同一发布矩阵还针对消费者安装包运行 `test/core/sqlite-driver.test.js`，验证原生
-选择边界，并对每个可用的可选 SQLite 候选执行真实 SQL、事务、JSON/RETURNING、
+同一发布矩阵还针对消费者安装包运行 `test/platform/sqlite-native.test.js`，验证所选
+驱动的分配/GC，并对每个可用的可选 SQLite 候选执行真实 SQL、事务、JSON/RETURNING、
 WAL 和备份检查。不可用候选会明确标记跳过，不视为兼容；正常选择路径仍必须通过。
 Doctor 冒烟报告选中的驱动、引擎和回退原因。该矩阵不能证明旧 glibc 环境兼容。
+纯选择/错误分类分支留在 `test/core/sqlite-driver.test.js`，执行一次。安装包 Doctor
+和原生 SQL 已证明的探针不在它们前面重复执行；仓库原生缓存仍在构建后验证，
+不跨 ABI 复用消费者的二进制。
 原生依赖检查必须通过 PTY 启动固定本地程序，确认输出和正常退出。安装包 smoke
 明确断言默认 Doctor 的 PTY 检查成功，并从消费者安装目录解析依赖。macOS 还会
 在可丢弃的依赖副本中移除 spawn-helper 执行权限，验证 Doctor 报出实际 helper
@@ -111,6 +160,11 @@ Doctor 冒烟报告选中的驱动、引擎和回退原因。该矩阵不能证
 不替换 Host。这是当前契约下的进程交接回归，不证明所有历史 Host 实现都兼容；
 这些检查不执行安装或发布效果。
 
+smoke 输出各阶段和总计（含清理）的 `TIMING`。分别测量构建、依赖安装/缓存恢复、
+纯测试与 npm install；Actions 总历时中的排队与重跑单列，不算作测试执行时间。
+保留现有 npm/原生缓存及精确 tarball 的校验和、provenance 门禁。registry 安装、
+Release 资产逐字节比较和 updater 验证证明不同边界，不能无等价身份绑定证据就删除。
+
 作为开发者或审查者的已配置 Agent 是普通执行资源。把一个真实 provider 或模型作为验证
 对象则不同：付费 API、共享 Home、生产系统、真实账号额度以及其他不可丢弃的外部效果，
 绝不由一个测试或验证请求隐含。它们需要用户就确切的资源和效果边界提出显式请求。

package/i18n/README.zh-CN.md

@@ -179,6 +179,10 @@ Agent 可以重新读取任务上下文，继续兼容的 Session，或在必要
 
 ### 产品结构
 
+Web 的 **设置 → 命令权限** 提供可搜索的只读“命令 × 角色”发现矩阵与内置能力契约。
+“发现可见”不代表具体调用已授权；页面不会修改权限规则或 Grant。
+详见[发现与授权说明](../docs/authorization.md#read-only-web-templates)。
+
 Yui 为你组织的东西 —— 是持久对象，而不是进程：
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "2.12.0",
+  "version": "2.15.0",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,