@zxyycom/vibe-check 0.0.2 → 0.0.3

package/docs/guides/callbacks.md

@@ -1,34 +1,93 @@
-# 按作用位置选择回调（Hook）
+# 生命周期位置与函数契约
 
-当你知道想在“执行前准备”“检查时决定结果”“显示时调整文本”或“结束后处理统计”，却不确定应该使用哪个回调时，从本文选择接入位置。本文按接入位置说明公开回调的分工；字段签名以 installed declarations 为准，项目定义与本次运行的参数归属见 [API 机制](../api-mechanics.md#参数应该放在哪里)。
+本页用“逻辑位置 → 实际执行契约”定位 Vibe Check 的扩展点。逻辑位置只说明某项职责相对领域事实发生的阶段；实际执行契约才定义路径、输入、调用次数、顺序、控制权和失败。相邻时点不表示共享 Hook。
 
-## 先按三条链路理解位置
+状态标记为：**当前公开**（package API）、**当前 Project**（Project Gate 自有）、**当前内部**（运行时私有）、**相邻 Change**（已有 owner、尚未接线）或**逻辑保留**（没有当前消费者）。只有当前实际契约给出可调用路径和签名。
 
-- **单项 Check**：被 Scheduler 准入 → `preflight` 准备 options → `execution` 形成结果 → Product 验证并结算。某项准备被阻断时不会继续 execution；不同 Check 可以并发。
-- **人读说明**：Check 用 `presentCheckFindings` 将 Finding 转成 messages 并附到自己的结果 → Product 显示明细时用 progress `formatter` 调整预览文本。前者在 Check 生成说明的位置，后者在终端显示的位置，两者都不替代检查结果的判定。
-- **调度策略**：graph 准备好后，可选 `prepare` 形成当前 Run 的策略 → Scheduler 调用 `decide` 零次或多次，每次同步返回一个 select / wait proposal → Scheduler 停止准入、等待已启动任务并封闭统计 → `measurementHooks` 观察终态 → 存在 terminal context 时调用可选 `complete`。simple strategy 不经过 `prepare`。
+## 当前时间线
 
-完整 Run 的验证、取消与输出衔接仍由 [API 生命周期](../api-mechanics.md#一次-run-的生命周期)说明。
+```text
+Definition / Controls validation
+→ effective flag selection
+→ static graph and admission-strategy preparation
+→ Scheduler admission
+  → admitted Check: prepare → execute → settle
+→ sealed Scheduler measurement
+  → internal summary → terminalEffects[] → prepared terminalEffect
+→ effective Check aggregation
+→ Run result and output closure
+→ Project Gate initial result → resultContributor → exit/transcript
+```
 
-## 回调的配置位置与权限
+早期取消、无效图和策略准备失败不会形成 sealed terminal measurement。Check `prepare` 只在该 Check 获准入后运行；它不是 invocation-wide hook。
 
-先确定要在什么位置做什么，再选择对应字段。下表用于定位，不是一条所有回调都会执行的串行流程：不同 Check 可以并发，progress 也会随运行持续呈现。
+## Product Check
 
-| 作用位置与目的 | 写在哪里 | 接收什么、产生什么 | 能改变的范围 |
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
 | --- | --- | --- | --- |
-| **调度开始前：准备本次调度策略** | Definition 的 [`scheduler.admissionPolicy.strategy`](scheduling.md#已准备的-custom-strategy) 选择 `kind: "prepared"`，提供 `prepare` | 接收静态 graph，返回本次使用的 `decide` 与可选 `complete` | 准备策略自己的运行状态，不执行 Check。 |
-| **调度选择时：决定建议先运行哪项** | [simple strategy 的 `decide`](scheduling.md#自定义准入-policy)，或 `prepare` 返回值中的 `decide` | 接收当前准入 context，同步返回 select / wait proposal | 只提出选择，Scheduler 仍检查依赖、互斥、容量与取消。 |
-| **单项 Check 被准入后、执行前：准备 options** | [`preflight`](extending-check-lifecycle.md#preflight准备阻止或带-fallback-继续) | 接收 authored options 和 signal，返回 prepared options、fallback 或阻断结果 | 影响这项 Check 是否继续及其 execution 输入，不是整个 Run 的前置 hook。 |
-| **单项 Check 执行时：检查并决定自己的结果** | [`defineCheck({ execution, ... })`](extending-check-lifecycle.md) | 接收 Check context，返回四态 terminal result，可报告 Records | 形成这项 Check 的领域结果；Product 验证并封闭事实，不开放事后改写结果的通用 hook。 |
-| **Check 生成 Finding 说明时：选择如何描述发现** | [`presentCheckFindings({ message, omittedMessage, ... })`](presenting-findings.md) | 单项 Finding 或省略集合转成 `CheckMessage`，helper 返回 messages | 由 Check 将说明附到自己的结果；不是终端 renderer，也不负责决定通过或失败。 |
-| **终端显示已结算 Check 的明细时：调整预览文本** | Definition 或 Controls 的 [`outputs.progressRendering.formatter`](run-outputs.md#配置-preview-文本) | 接收选中项的默认文本和预算，同步返回替代文本 | 只改变终端预览，不改写完整 Records、messages 或 Check outcome。 |
-| **调度停止且已启动任务结束后：观察终态统计** | Definition 的 [`scheduler.measurementHooks`](scheduling.md#观察终态-measurement) | 接收冻结的 graph、settlement observations 与 raw measurement | 消费或保存终态观察，不能重跑任务或改写 Check facts。 |
-| **终态观察交付后：完成本次已准备策略** | `prepare` 返回值中的可选 `complete` | 存在 sealed terminal context 时接收该 context，至多调用一次 | 完成策略自己的终态工作；不是保证所有失败路径都会调用的通用 `finally`。 |
+| 单项 options 准备 | **当前公开**：`Definition.checks[].prepare`，`CheckPreparation` | admitted Check 至多一次、早于 `execute`；block、throw 或非法结果只将该 Check 结算为 unavailable。 | [自定义 Check](extending-check-lifecycle.md) |
+| 开始执行 | **当前内部**：`CheckExecutionLifecycle.started` | prepare 成功后、execute 前同步投影；不能控制结果。 | Product Run |
+| 领域执行 | **当前公开**：`Definition.checks[].execute` | 形成本 Check result、messages 与 Records。 | [自定义 Check](extending-check-lifecycle.md) |
+| 单项结算 | **当前内部**：`CheckExecutionLifecycle.settled` | Core 接受唯一终态事实后同步一次，覆盖 control、dependency、preparation、execution 和取消。 | Product result model |
 
-## 结算结果与结算后工作
+```ts
+const check = defineCheck({
+  checkId: "license-policy",
+  displayName: "License policy",
+  options: { denied: ["GPL-3.0-only"] },
+  prepare(options) {
+    return { status: "success", preparedOptions: options };
+  },
+  execute({ options }) {
+    return { status: "passed", data: { deniedCount: options.denied.length } };
+  }
+});
+```
 
-**“结算结果”和“结算后做事”不同。** Check 的 `execution` 与领域 policy 决定本项结果；本次 `checkAggregation` 从已结算状态派生 Run aggregate，它是配置而不是回调。若要根据完整 `RunResult` 决定 CI 退出码或做项目后处理，在项目代码 `await run(...)` 之后处理；这不是 Product 提供的另一组生命周期 hook。
+## Project / invocation
 
-## 回调失败如何反馈
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| Project facts 准备 | **相邻 Change** | `add-project-change-flags` 拥有选择前 Project facts；本 Change 不建立 callback。 | Project Definition owner |
+| 有效选择完成 | **当前内部**：`InvocationLifecycle.selectionSettled()` | 所有 flag-control settlements 被接受后、Scheduler graph run 前一次；与逐 Check 生命周期分离。 | Project Run owner |
+| 批量有效输入准备 | **相邻 Change** | `batch-declared-project-file-inputs` 拥有选择后的输入屏障。 | Project Run owner |
+| 有效 Check 汇总 | **当前公开**：`RunControls.checkAggregation(checks)` | 完整结算后至多一次；接收只读、canonical-order 的有效 `CoreCheck[]`，必须同步返回四态。省略时 Product strict-all；throw、Promise 或非法返回直接拒绝 `run`，不是 `RunResult` hook。 | [API 机制](../api-mechanics.md#runcontrols-与-check-aggregation) |
+
+## Admission / Scheduler
+
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| 策略准备 | **当前公开**：prepared strategy `prepare(context)` | static graph 有效后至多一次，返回 `decide` 和可选 `terminalEffect`。 | [调度 Check](scheduling.md) |
+| 准入决策 | **当前公开**：simple/prepared `.decide(context)` | 每个 decision boundary 同步提出 select/wait；Scheduler 验证并转换状态。 | Scheduler |
+| accepted action 测量 | **当前内部**：private collector | accepted transition 后记录，下一次 decide 只读取冻结 prefix。 | Scheduler owner |
+| 终态摘要 | **当前内部**：summary participant | sealed context 后最先运行并自行 contain writer failure。 | Scheduler owner |
+| 终态作用 | **当前公开**：`scheduler.terminalEffects[]` | internal summary 后依声明顺序 await；任一失败不阻止后续作用。 | [调度 Check](scheduling.md) |
+| prepared 策略终态作用 | **当前公开**：prepared `terminalEffect` | public effects 后、sealed context 存在时至多一次；与数组共享 `outputs.terminalEffects`。 | Scheduler owner |
+| 必达资源释放 | **逻辑保留** | 没有当前公开消费者；terminalEffect 不是 `finally`。 | future Change |
+
+terminal effect 可读取冻结 `SchedulerMeasurementContext`，不能修改 Scheduler 或 Check 结果。任一公开或 prepared effect 失败会使 `outputs.terminalEffects` 为 failed；正常 completed Run 映射为 `kind: "output"` / `scheduler-terminal-effects-failed`，取消或其它 primary failure 保持原结果。
+
+## Run output
+
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| Check preview | **当前公开**：`outputs.progressRendering.formatter` | 只格式化受预算限制的显示文本。 | [Run outputs](run-outputs.md) |
+| terminal-effect readback | **当前公开**：`RunResult.outputs.terminalEffects` | 汇总 Definition effects 与 prepared effect；Controls 不能注入。 | Run output owner |
+| Run result handling / policy | **逻辑保留** | 调用方在 `await run(...)` 后自行处理；Product 未提供内部 policy hook。 | future Change |
+
+## Project Gate
+
+| 逻辑位置 | 状态与路径 | 职责、顺序与失败 | owner |
+| --- | --- | --- | --- |
+| Gate 结果贡献 | **当前 Project**：`PROJECT_GATE_RUN_CONFIG.resultContributor(context)` | exact candidate Run 形成 `initialResult` 后至多一次；只能返回已验证 message list。 | Project Gate |
+| Gate 结果决定 | **当前内部**：initial result → contribution → exit mapper | adapter 追加 messages、原样保留 initial status；throw 或非法列表为 unavailable。 | Project Gate owner |
+| transcript 完成 | **当前内部**：`ProjectGateTranscript.complete` | final result 与 exit 已确定后写入一次；失败 fail closed。 | Project Gate owner |
+
+`resultContributor` 不是 package API、插件系统或完整结果 transform。它能读 `initialResult`、selection、candidate、timing 与 Run facts，但不能重写 status。
+
+## 精确契约
 
-`preflight` / `execution` 的失败由 owning Check 结算。progress formatter、measurement Hooks 与 prepared `complete` 的失败通过对应 output status 反馈，并保留已形成的 Check facts；原本正常完成的 Run 会成为 `kind: "output"`，已有取消或执行失败则保留主结果。完整优先级见[输出状态与失败处理](run-outputs.md#输出状态与失败处理)。
+- Check authoring、取消、reason 和 callback context： [自定义 Check](extending-check-lifecycle.md)。
+- Definition validation、closed grammar 和 fingerprint：Project Definition owner（工作区维护材料）。
+- Scheduler measurement、策略及 output priority： [调度 Check](scheduling.md) 与 [Run outputs](run-outputs.md)。
+- Gate candidate binding、result contribution、exit 与 transcript：Project Gate owner（工作区维护材料）。

package/docs/guides/check-dependencies.md

@@ -1,6 +1,15 @@
 # 读取 Check 依赖与类型化数据
 
-需要把一项 Check 的结果交给另一项使用时，先声明 direct `dependsOn` 或 `observes`，再通过 dependency reader 读取上游结果，并用 provider parser 恢复业务类型。需要上游通过才开始时选择 `dependsOn`；需要审计任意终态时选择 `observes`。这些关系还约束 Scheduler 准入，调度预算见[调度 Check](scheduling.md)。
+需要把一项 Check 的结果交给另一项使用时，先声明 direct `dependsOn` 或 `observes`，再通过 dependency reader 读取上游结果，并用 provider parser 恢复业务类型。需要上游通过才开始时选择 `dependsOn`；需要审计任意终态时选择 `observes`。若同一次 Run 的 direct prerequisite 还必须交接不能 canonicalize 的 reference（例如 `Map` 或 typed bytes），provider 在 `defineCheck` 中声明 `handoff: true`，consumer 才能以 provider object 读取它。这些关系还约束 Scheduler 准入，调度预算见[调度 Check](scheduling.md)。
+
+## 先选择读取契约
+
+| consumer 要解决的问题 | provider 声明与 consumer 读取 | 不能获得的能力 |
+| --- | --- | --- |
+| 只需要已结算的 canonical final data，或需要审计任意终态 | 以 `dependsOn` 或 `observes` 声明 relation；使用 string `get(checkId)` 或 `list()` | 不保留原始 reference identity，也不能读取未声明或传递 provider。 |
+| 必须在同一次 Run 内交接不可 canonicalize 的 reference | provider 声明 `handoff: true`，在 `passed` 返回 `handoff`；consumer 将 provider 设为 direct `dependsOn` 并调用 `get(provider)` | 不授权 `observes`、string ID、传递 provider 或任何 Run 外读取；reference 不会发布。 |
+
+`handoff: true` 是唯一的 authoring declaration：它必须写在 `defineCheck(...)` 的 executable provider 上，不是数据、parser、serializer 或 author 创建的 token。Product 在 package-runtime 内部的 WeakMap 注册该 provider identity；identity 只连接已定义 provider、Definition 与 execution，不是 package API 或跨 package instance 的兼容协议。每次 Run 的 private store 才暂存已接受的 handoff reference。`handoff` 只可为 executable provider 的精确 `true`；container、其它值和自有 `undefined` 都会在 Definition validation 被拒绝。
 
 ## 完整运行示例
 
@@ -17,6 +26,8 @@ type ChangedFilesData = Readonly<{
 const changedFiles = defineCheck({
   checkId: "changed-files",
   displayName: "Changed files",
+  // `true` 是唯一的 runtime declaration；返回值的 handoff 类型由 execution 自动推断。
+  handoff: true,
   parseData(data): ChangedFilesData {
     if (
       data.version !== CHANGED_FILES_DATA_VERSION ||
@@ -27,10 +38,14 @@ const changedFiles = defineCheck({
     }
     return { files: data.files, version: data.version };
   },
-  execution() {
+  execute() {
+    const bytesByPath = new Map<string, Uint8Array>([
+      ["src/index.ts", new TextEncoder().encode("export {}\n")]
+    ]);
     return {
       status: "passed",
-      data: { files: ["src/index.ts"], version: CHANGED_FILES_DATA_VERSION }
+      data: { files: ["src/index.ts"], version: CHANGED_FILES_DATA_VERSION },
+      handoff: bytesByPath
     };
   }
 });
@@ -39,12 +54,21 @@ const analyzeChangedFiles = defineCheck({
   checkId: "analyze-changed-files",
   displayName: "Analyze changed files",
   dependsOn: [changedFiles.checkId],
-  execution({ dependencies }) {
-    const read = dependencies.get(changedFiles.checkId);
+  execute({ dependencies }) {
+    const read = dependencies.get(changedFiles);
     if (!read.ok) return { status: "unavailable", reason: { code: read.error.code } };
 
+    // canonical data 仍在 parser 边界；handoff 保留 same-Run reference identity。
     const data = changedFiles.parseData(read.data);
-    return { status: "passed", data: { analyzedFileCount: data.files.length } };
+    const firstFile = data.files[0];
+    const firstFileBytes = firstFile === undefined ? undefined : read.handoff.get(firstFile);
+    if (firstFileBytes === undefined) {
+      return { status: "unavailable", reason: { code: "changed-file-bytes-unavailable" } };
+    }
+    return {
+      status: "passed",
+      data: { analyzedByteCount: firstFileBytes.byteLength, analyzedFileCount: data.files.length }
+    };
   }
 });
 
@@ -61,7 +85,13 @@ const result = await run(definition);
 if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
 ```
 
-上例先收窄 `get` 的 `ok`，再显式调用 producer 的 `parseData`。`dependsOn` 保证 callback 只在 provider `passed` 后开始；`!read.ok` 仍作为读取边界防御。八个随包 Check 都提供 `parseData` 和同实现的 package-root parser，名称与类型见各自指南。
+上例的 `handoff: true` 是 provider 的最小 runtime declaration；`passed` result 中的 `Map<string, Uint8Array>` 自动成为 provider-aware read 的 handoff 类型。provider 只能在 `passed` branch 返回同型、non-null 的 `handoff`；`dependencies.get(changedFiles)` 只在 current Run 中由 direct `dependsOn` consumer 成功，返回 provider 的 canonical `data` 和同一 `Map` reference。fan-out consumer 读取的也是这个引用，而 repeated Run 不共享它。
+
+先收窄 `get` 的 `ok`，再显式调用 producer 的 `parseData(read.data)`：parser 继续只负责 detached、deep-frozen canonical data，绝不解析或 clone `handoff`。`dependsOn` 保证 callback 只在 provider `passed` 后开始；`!read.ok` 仍是读取边界防御。九个随包 Check 都提供 `parseData` 和同实现的 package-root parser，名称与类型见各自指南。
+
+provider-object read 的失败不返回上游 `data` 或 `handoff`：输入不是 `handoff: true` 定义的 provider，或不是 effective direct `dependsOn` 时，错误为 `dependency-not-declared`；已获 direct authorization 但本次 execution 没有接受到该 provider 的 `passed` handoff 时，错误为 `upstream-handoff-unavailable`。consumer 必须像示例一样先处理 `!read.ok`，不能把 TypeScript 推断当作运行时授权。
+
+handoff 保留 identity，因此 Product 不会 freeze、clone、serialize、缓存或验证其领域含义。producer 与所有 consumer 必须把它作为 immutable observation：上例不调用 `Map#set`，也不改写其中的 `Uint8Array`。execution graph 结束时 Product 清空自己的 private-store reference；该 `clear()` **不是** disposer，不会调用 `close`、`dispose` 或任意 symbol hook。真实资源的创建者/调用方必须以显式 graph ordering、consumer `try/finally` 或 Run 外层 lifecycle 在最后一个 consumer 后清理，不能依赖 handoff store、GC 或 machine/diagnostic publication。
 
 ## 批量审计 direct outcomes
 
@@ -72,7 +102,7 @@ const auditChangedFiles = defineCheck({
   checkId: "audit-changed-files",
   displayName: "Audit changed files",
   observes: [changedFiles.checkId, analyzeChangedFiles.checkId],
-  execution({ dependencies }) {
+  execute({ dependencies }) {
     const observations = dependencies.list();
     const readable = observations.filter(
       ({ outcome }) =>
@@ -104,7 +134,7 @@ const auditChangedFiles = defineCheck({
 
 ## Provider 类型与解析边界
 
-通过 `defineCheck({ execution, parseData })` 建立 typed provider：同步 parser 的返回类型同时约束该 Check 的 `passed` / `failed` data，返回值保留必需的 `parseData`。普通递归 `Check` 类型本身不声明 parser；仅写 `satisfies Check` 或 inline `defineConfig` 不建立该类型关系。没有 parser 的普通 Check 仍合法，container 则不能声明 parser。
+通过 `defineCheck({ execute, parseData })` 建立 typed provider：同步 parser 的返回类型同时约束该 Check 的 `passed` / `failed` data，返回值保留必需的 `parseData`。普通递归 `Check` 类型本身不声明 parser；仅写 `satisfies Check` 或 inline `defineConfig` 不建立该类型关系。没有 parser 的普通 Check 仍合法，container 则不能声明 parser。
 
 TypeScript 拒绝 async 或返回 `PromiseLike` 的 parser，即使推断结果类型很宽。canonical JSON 中非 callable 的 `then` 字段仍是普通数据。JavaScript 或显式 cast author object 上的 function parser 可以通过 runtime Definition validation，但不会因此取得 TypeScript 关系；自有 `parseData: undefined` 规范化为省略。
 
@@ -115,7 +145,8 @@ parser 接收 Check-facts-owned 的 detached、deep-frozen canonical object，
 ## Direct relation 与读取规则
 
 - `dependsOn` 与 `observes` 命名同一 Definition 中的 executable Check。两者各自可继承父 collection；精确数组完整替换（`[]` 清空），`inherit({ add, remove })` 显式增删后去重。一个 provider 不得同时出现在两类 relation 中。
-- `dependsOn` 等所有 direct provider 通过才允许本 Check 的 preflight/execution；任一 provider 非 `passed` 时，本 Check 在 author work 前成为 `unavailable / dependency-not-passed`，reason 带 direct blocker `checkIds`，duration 为 `null`。`observes` 只等待终态，不要求通过。
+- `dependsOn` 等所有 direct provider 通过才允许本 Check 的 preparation/execution；任一 provider 非 `passed` 时，本 Check 在 author work 前成为 `unavailable / dependency-not-passed`，reason 带 direct blocker `checkIds`，duration 为 `null`。`observes` 只等待终态，不要求通过。
 - `get(checkId)` 是 non-generic string read，只授权 normalized effective `dependsOn ∪ observes` 的 direct ID（包括各自继承项）。未声明、传递或 malformed ID 返回不泄露 upstream fact 的 `dependency-not-declared`。
+- `get(provider)` 是 provider-aware read，只接受以 `handoff: true` 定义的 provider object，并且只授权 normalized effective direct `dependsOn`。成功时固定为该 provider literal `checkId`、`status: "passed"`、canonical `data` 与 typed `handoff`；direct `observes`、transitive、未声明、lookalike provider 或本次未接受 handoff 都 fail closed，不泄露 upstream data/reference。它不改变 string `get(checkId)` 或 `list()` 的授权、shape 与四态 observation。
 - 已声明 provider 的 `passed` / `failed` 返回 `ok: true`、status 与 canonical data；`not-applicable` / `unavailable` 返回 `ok: false`、该 status 与 `upstream-data-unavailable`。TypeScript 类型本身不授予访问权。
 - `list()` 无参返回同一 direct union 的完整四态 observations，按 normalized effective direct ID 稳定排序并去重；数组、每项与 Core-owned outcome 都冻结。不读取传递、未声明或 ambient executed Checks，也不提供 Records、scheduler timing 或全局历史。

package/docs/guides/collecting-project-files.md

@@ -25,7 +25,7 @@ if (!Object.isFrozen(selectedPaths)) {
 
 ## 共享的 files 选择语义
 
-需要选择项目文件的随包 Check 使用 `{ source, include, exclude }`：`source` 明确选择 `filesystem` 或 `git-worktree`，include/exclude 使用 project-root-relative、`/` 分隔的 minimatch glob，点号开头的路径也参与匹配，exclude 优先。来源不可用时不切换来源；Check 将它结算为 `unavailable`，下方独立工具则同步 throw。
+需要选择项目文件的随包 Check 使用 `{ source, include, exclude }`：`source` 明确选择 `filesystem` 或 `git-worktree`，include/exclude 使用 project-root-relative、`/` 分隔的 minimatch glob，点号开头的路径也参与匹配，exclude 优先。Project change regions 复用同一 include/exclude matcher，但只对 Git 已得出的 changed-path candidates 匹配，不重新枚举 project files。来源不可用时不切换来源；Check 将它结算为 `unavailable`，下方独立工具则同步 throw。
 
 `defaultProjectFileSelection` 是深冻结、可组合的基线，不是全局配置。它排除常见 VCS/Product state、dependencies、build/generated、cache、coverage、log、temporary 与 virtual-environment paths。`duplicateDetection`、`fileMetrics` 与 `jsonSchemaValidation` 原样采用该基线；`functionMetrics`、`jsonValidation` 与 `markdownLinkValidation` 保留 source/exclude，按支持文件类型派生默认 include。`secretDetection` 要求显式完整 selection。精确默认列表可从导出值读取，各 Check 的实际默认与 eligibility 见其指南。
 
@@ -35,12 +35,12 @@ Check constructor 接受省略字段时，由 owning Check 物化默认值；显
 
 每次调用都必须给出 `projectRoot` 与完整 `selection: { source, include, exclude }`：
 
-| 输入 | 要求与作用 |
-| --- | --- |
-| `projectRoot` | 非空且不含 U+0000 的路径；相对路径从调用时的工作目录解析，绝对路径直接使用。示例的 `"."` 是调用方显式选择当前目录，并非省略字段的默认值。 |
-| `selection.source` | 只能是 `"filesystem"` 或 `"git-worktree"`，决定候选路径来源。 |
-| `selection.include` | 无空洞的字符串数组，每项是相对 root、使用 `/` 的 glob；路径至少命中一项才被选中，`[]` 不选择任何路径。 |
-| `selection.exclude` | 同样是无空洞的字符串数组；命中任一 glob 就排除，`[]` 不增加排除条件。排除优先于包含。 |
+| 输入                | 要求与作用                                                                                                                                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `projectRoot`       | 非空且不含 U+0000 的路径；相对路径从调用时的工作目录解析，绝对路径直接使用。示例的 `"."` 是调用方显式选择当前目录，并非省略字段的默认值。 |
+| `selection.source`  | 只能是 `"filesystem"` 或 `"git-worktree"`，决定候选路径来源。                                                                             |
+| `selection.include` | 无空洞的字符串数组，每项是相对 root、使用 `/` 的 glob；路径至少命中一项才被选中，`[]` 不选择任何路径。                                    |
+| `selection.exclude` | 同样是无空洞的字符串数组；命中任一 glob 就排除，`[]` 不增加排除条件。排除优先于包含。                                                     |
 
 这些对象只接受列出的自有数据字段，不接受额外字段或 getter/setter；数组也不接受额外属性或 accessor 元素。工具不在遗漏 root 时替调用方选择目录；显式 root 不是路径隔离、文件系统沙箱或文件内容可读性的承诺。
 

package/docs/guides/command-check.md

@@ -0,0 +1,155 @@
+# 执行外部命令的 Check
+
+`commandCheck(...)` 将一个单一、无 shell 的外部 command 接入 ordinary Check lifecycle。Product 负责进程启动、协作取消、超时、受限输出捕获和默认终态；调用方可在 spawn 前解析本次 environment，并在完整命令结果上完成领域结算。
+
+默认模式适合 exit status 已足够表达检查结果的工具。需要将完整 command 的 stdout/stderr 转为领域 data、Records 或 typed provider 时，使用 `afterCommand`；工具协议、参数语义、解析规则和保存的业务数据始终由调用方拥有。
+
+## 最小用法
+
+下例以当前 Node executable 构造一个通过的 Check。`process.execPath` 是绝对 executable path，不依赖 shell 或 `PATH`；省略的 environment 使用 exact-empty，output 使用 discard。
+
+```ts
+import { commandCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+const nodeProbe = commandCheck({
+  checkId: "node-probe",
+  displayName: "Node probe",
+  executable: process.execPath,
+  arguments: ["--eval", "process.exit(0)"],
+  timeoutMs: 5_000,
+  outputByteLimit: 64 * 1024
+});
+
+const definition = defineConfig({
+  checks: [nodeProbe],
+  outputs: {
+    diagnosticLogging: { enabled: false },
+    machinePublication: { enabled: false },
+    progressRendering: { enabled: false }
+  }
+});
+
+const result = await run(definition);
+if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+const outcome = result.snapshot.checks.find(
+  ({ checkId }) => checkId === nodeProbe.checkId
+)?.outcome;
+if (outcome?.status !== "passed" || outcome.data.exitCode !== 0) {
+  throw new Error("Node probe did not produce the expected passed outcome");
+}
+```
+
+## 输入与 ordinary Check 组合
+
+`commandCheck<Id>(input)` 返回 ordinary Check，且 `checkId` 保留调用方的 literal type。`checkId`、`displayName`、`executable`、`timeoutMs` 与 `outputByteLimit` 必填；constructor 对 closed input policy 做 runtime validation，非法 input 抛出 `TypeError`。preparation 再次无法验证 options 时，该 Check 结算为 `unavailable / invalid-options`。
+
+它还接受 ordinary authoring 的 `enabledByFlags`、`checks`、`dependsOn`、`observes`、`maxParallel`、`admissionPriority`、`mutex`、`resourceClaims` 与 `omitQuietPassedRow`。选择、依赖和调度语义由[自定义 Check](extending-check-lifecycle.md)与[调度 Check](scheduling.md)拥有。
+
+| 字段 | 要求与默认值 |
+| --- | --- |
+| `executable` | 必填：非空且不含 NUL 的 executable；可为绝对 path 或由平台在最终 environment 中解析的名称。 |
+| `arguments` | 可选，默认 `[]`：dense readonly string array；元素可为空但不得含 NUL，每个元素作为独立 argv 传递。 |
+| `workingDirectory` | 可选，默认 project root：非空且不含 NUL；relative path 从 project root 解析，absolute path 保持原 target。 |
+| `environment` | 可选，默认 `{ mode: "exact" }`。它与 `resolveEnvironment` 互斥，见[环境](#环境)。 |
+| `resolveEnvironment` | 可选：在 spawn 前为本次 invocation 返回 closed environment policy，见[环境](#环境)。 |
+| `timeoutMs` | 必填：正安全整数，限定一次 command execution。 |
+| `outputByteLimit` | 必填：正安全整数，stdout 和 stderr 各自的 byte ceiling。 |
+| `output` | 可选，默认 `{ mode: "discard" }`。见[输出](#输出)。 |
+| `afterCommand` | 可选：完整 numeric-exit command 的 caller-owned completion，见[调用方完成阶段](#调用方完成阶段)。 |
+
+command 由 executable 和独立 arguments 表示，不是 shell string、pipeline 或 workflow。
+
+## 环境
+
+环境是 closed policy。静态 `environment` 与 invocation-time `resolveEnvironment` 互斥；两者都省略时，child 使用 exact-empty environment。
+
+| policy | child base environment |
+| --- | --- |
+| `{ mode: "exact", variables? }` | 只使用 `variables` 中的 `Record<string, string>`；省略 variables 即 exact-empty。 |
+| `{ mode: "inherit", overrides? }` | execution start snapshot `process.env`；string override 覆盖 key，`null` 删除 key。 |
+
+这张 policy 只确定 caller base environment。Product 在它之后加入固定 plain-text/no-color variables：`CARGO_TERM_COLOR=never`、`CLICOLOR=0`、`CLICOLOR_FORCE=0`、`FORCE_COLOR=0`、`NO_COLOR=1`、`PNPM_CONFIG_COLOR=false`、`PY_COLORS=0`、`TERM=dumb`、`UV_NO_COLOR=1` 与 `npm_config_color=false`。这些 keys 最后覆盖静态 policy 或 resolver 返回 policy 中的同名 value；不能通过此 API 请求 colorized child output。
+
+`resolveEnvironment(context)` 在 spawn 前接收 `project`、direct `dependencies`、prepared command `options` 和取消 `signal`，并返回（或 resolve 为）同一张 policy 表中的值。其返回值同样先作为 caller base environment，再由 Product 加入上述固定 keys。它适合把当前 project 或已声明依赖转换为本次 command 的最小环境：
+
+```ts
+const projectCommand = commandCheck({
+  checkId: "project-command",
+  displayName: "Project command",
+  executable: process.execPath,
+  arguments: ["--eval", "process.exit(0)"],
+  resolveEnvironment: ({ project }) => ({
+    mode: "exact",
+    variables: { PROJECT_ROOT: project.root }
+  }),
+  timeoutMs: 5_000,
+  outputByteLimit: 64 * 1024
+});
+```
+
+resolver throw 或返回非法 policy 时，不启动 child，Check 结算为 `unavailable / command-environment-resolution-failed`。environment names、values 与 policy object 拒绝 unknown fields、accessor/prototype tricks、`undefined`、非 string 值及 NUL；resolved environment 不会自动进入 Check facts、messages 或 diagnostics。
+
+## 输出
+
+`output` 只选择 child material 的处理边界，不改变默认 terminal mapping。
+
+| policy | 行为 |
+| --- | --- |
+| `{ mode: "discard" }` | 默认。Product 在受 `outputByteLimit` 约束的 invocation memory 中捕获 stdout/stderr，并在结算后释放；它不自动发布 child material。 |
+| `{ mode: "transcript" }` | Product 将 running state 与 final status metadata、raw stdout、raw stderr 原子写入此 Check artifact directory 的固定 `process.log`。 |
+
+transcript 是显式 opt-in artifact capability。没有 `artifactDirectory`，或 running/final write 失败时，Check 为 `unavailable / command-transcript-unavailable`。`process.log` 不包含 executable、arguments、environment 或 native error text。
+
+## 调用方完成阶段
+
+`afterCommand` 把完成 callback 与可选 typed-provider parser 放在同一个对象：
+
+```ts
+const reportCommand = commandCheck({
+  checkId: "report-command",
+  displayName: "Report command",
+  executable: process.execPath,
+  arguments: ["--eval", 'process.stdout.write("report")'],
+  timeoutMs: 5_000,
+  outputByteLimit: 64 * 1024,
+  afterCommand: {
+    execute: ({ command, records }) => {
+      records.report({ id: "report-command" }, { stdoutLength: command.stdout.length });
+      return { status: "passed", data: { report: command.stdout } };
+    },
+    parseData: (data) => {
+      if (typeof data.report !== "string") throw new TypeError("report must be a string");
+      return { report: data.report };
+    }
+  }
+});
+```
+
+Product 只在 child 具有 numeric exit，且未取消、未 timeout、未达到 output limit、未被 signal 终止时调用 `afterCommand.execute`。若选择 transcript，final write 也必须先成功。callback context 是 ordinary `CheckExecutionContext` 加上 invocation-local `command: { exitCode, stdout, stderr }`；它可以返回普通 `CheckResult` 并按 ordinary Check contract 报告 Records。这个返回值取代完整命令的默认 exit-code mapping。
+
+存在 `parseData` 时，返回值是 typed provider Check，parser 负责验证 callback 返回的 data；没有 parser 时，返回值仍是 ordinary Check。`stdout`、`stderr` 仅在 callback context 中提供，不会因 callback 存在而自动发布。调用方决定是否把派生数据或 Records 放入自己的结果边界，并负责其中的敏感信息处理。
+
+## 默认终态与失败边界
+
+未使用 `afterCommand` 时，完整 numeric exit 的 `passed` 和 `failed` 返回 `CommandCheckFinalData` 的 `{ exitCode: number }`；command-owned unavailable 分支使用 `CommandCheckUnavailableReasonCode`。
+
+| process cause | 默认 Check terminal outcome |
+| --- | --- |
+| exit code `0` | `passed / { exitCode: 0 }` |
+| numeric nonzero exit | `failed / { exitCode }` |
+| startup failure | `unavailable / command-start-failed` |
+| resolver throw 或非法 policy | `unavailable / command-environment-resolution-failed` |
+| timeout | `unavailable / command-timeout` |
+| stdout 或 stderr 达到 byte limit | `unavailable / command-output-limit-exceeded` |
+| 非 timeout、非 cancellation signal | `unavailable / command-terminated-by-signal` |
+| transcript capability 或 write failure | `unavailable / command-transcript-unavailable` |
+| 无法验证 prepared options | `unavailable / invalid-options` |
+| Core 观察到 caller cancellation | `unavailable / execution-cancelled` |
+
+同时出现多个底层终态标记时，Product 以 **nonzero exit → cancellation → timeout → max-buffer → signal → startup failure → zero exit** 的顺序选择默认 cause。只有完整 numeric exit 才能进入 `afterCommand`；其它分支保留 Product-owned mapping。callback 自身的 throw 或 settlement 继续由 ordinary Check/Core lifecycle 处理。
+
+## 安全边界与公开类型
+
+默认 exact-empty environment 与 discard output 避免 ambient credential 和 child material 自动进入结果或日志。选择 `inherit`、`transcript` 或在 `afterCommand` 发布派生数据时，调用方负责对应 environment、artifact 和结果边界的访问控制、保留和清理。
+
+package root 提供 `commandCheck` 及 `CommandCheckInput`、`CommandCheck`、`CommandCheckWithAfterCommand`、`TypedCommandCheck`、`CommandCheckEnvironment`、`CommandEnvironmentContext`、`CommandEnvironmentResolver`、`AfterCommand`、`AfterCommandContext`、`AfterCommandExecution`、`CompletedCommand`、`CommandCheckOutput`、`CommandCheckFinalData` 与 `CommandCheckUnavailableReasonCode`；精确签名见安装包 declarations。它不提供 shell、pipeline、workflow 或 process-exit adapter，也不保证平台解析的 command 存在。

package/docs/guides/data-boundaries.md

@@ -0,0 +1,140 @@
+# Core 数据工具：JSON 规范化与结构快照
+
+这两组公开 Core 工具让调用方复用 Core 的数据处理规则：取得独立的 JSON 数据副本、生成确定性文本或字节，
+或检查配置对象和数组的外层结构。它们都从 package root 导入，无需创建 Check、Project Definition 或 Run。
+工具只负责下表所列的数据处理；调用方仍负责字段含义、取值范围和业务规则。
+
+## 选择工具
+
+两组工具解决不同问题，不是一条必须依次调用的流水线。
+
+| 需要的结果 | 选择 | 成功结果 | 不符合输入规则时 |
+| --- | --- | --- | --- |
+| 独立、递归冻结的 JSON 数据副本 | `canonicalizeJsonValue`；顶层必须是非数组对象时用 `canonicalizeJsonObject` | 规范化后的 JSON 值或对象 | 返回 `undefined` |
+| 确定性 JSON 文本或 UTF-8 字节 | `canonicalJsonText` / `canonicalJsonBytes` | 文本 / `Uint8Array`，内部已执行规范化，无须先调用 `canonicalize*` | 抛出 `TypeError` |
+| 字段恰好匹配的配置对象，或无空洞的标准数组 | `snapshotExactClosedRecord` / `snapshotClosedArray` | 冻结的浅副本，保留字段值或元素的引用 | 返回 `undefined` |
+
+JSON 规范化/序列化工具只接受下文定义的 JSON 数据；结构快照不要求字段值或元素是 JSON，因而也适合包含
+回调的配置。两组工具可分别使用：不先做结构快照，也能规范化或序列化；不先规范化，也能做结构快照。
+输入可以是程序构造的值，也可以是解析得到的数据；是否来自外部，不改变各工具的输入规则。
+
+## 取得独立的 JSON 副本
+
+当需要保留一份不会被调用方后续修改影响的数据时，使用规范化工具。对象版本直接约束顶层类型；
+value 版本也接受数组和 JSON 基本值。两者都会递归复制并冻结支持的数据，而不是冻结原对象。
+
+```ts
+import { canonicalizeJsonObject, canonicalizeJsonValue } from "@zxyycom/vibe-check";
+
+const authoredLimits = { maxFindings: 10 };
+const limits = canonicalizeJsonObject(authoredLimits);
+if (limits === undefined) throw new TypeError("Expected JSON object limits.");
+
+authoredLimits.maxFindings = 20;
+if (limits.maxFindings !== 10 || !Object.isFrozen(limits)) {
+  throw new Error("Expected an independent frozen limits object.");
+}
+
+// 顶层不一定是对象时，选择 value 版本。
+const fileList = canonicalizeJsonValue(["src/index.ts"]);
+if (!Array.isArray(fileList) || !Object.isFrozen(fileList)) {
+  throw new Error("Expected a frozen JSON array.");
+}
+```
+
+## 生成确定性文本或字节
+
+调用方先决定哪些字段参与比较或缓存身份，再选择文本或字节输出。同一组数据仅改变对象属性的插入顺序，
+不会改变输出；数组元素顺序仍然有意义。字节版本可直接用于摘要计算或二进制接口，不要求调用方重复编码步骤。
+摘要计算本身和缓存 key 的完整性不由这些工具负责。
+
+```ts
+import { canonicalJsonBytes, canonicalJsonText } from "@zxyycom/vibe-check";
+
+// 调用方决定哪些字段影响计算结果；工具只负责一致的数据表示。
+const cacheInputs = { mode: "strict", paths: ["src/index.ts"] };
+const keyText = canonicalJsonText(cacheInputs);
+const keyBytes = canonicalJsonBytes(cacheInputs);
+
+if (
+  keyText !== canonicalJsonText({ paths: ["src/index.ts"], mode: "strict" }) ||
+  new TextDecoder().decode(keyBytes) !== keyText
+) {
+  throw new Error("Expected one deterministic representation for the selected cache inputs.");
+}
+```
+
+## 检查含回调的配置结构
+
+结构快照可保留函数、`undefined` 和嵌套引用。先检查外层有哪些字段，再验证字段内容；需要检查嵌套数组时，
+单独调用数组工具。它们不把整个配置转换为 JSON，也不深复制或冻结回调及其关联对象。
+
+```ts
+import { snapshotClosedArray, snapshotExactClosedRecord } from "@zxyycom/vibe-check";
+
+const onComplete = () => "done";
+const authoredTask = { name: "build", onComplete, paths: ["src/index.ts"] };
+const task = snapshotExactClosedRecord(authoredTask, ["name", "onComplete", "paths"]);
+if (task === undefined || typeof task.name !== "string" || typeof task.onComplete !== "function") {
+  throw new TypeError("Expected a closed task configuration with a name and callback.");
+}
+
+// 外层字段检查不验证 paths 的内容；数组结构和元素语义分别检查。
+const selectedFiles = snapshotClosedArray(task.paths);
+if (selectedFiles === undefined || !selectedFiles.every((path) => typeof path === "string")) {
+  throw new TypeError("Expected a dense list of file paths.");
+}
+if (task.onComplete !== onComplete || task.paths !== authoredTask.paths) {
+  throw new Error("Expected the shallow snapshot to preserve callback and nested references.");
+}
+```
+
+## Canonical JSON
+
+### 输入与副本
+
+输入接受 `null`、boolean、string、有限 number、使用 `Array.prototype` 的无空洞数组，以及使用
+`Object.prototype` 或 null prototype 的对象。拒绝 `undefined`、非有限 number、function、symbol、bigint、
+循环引用、存取器属性、不可枚举的自有属性、数组额外自有属性和其它原型。数组自身的标准 `length` 属性是例外。
+共享但非循环的引用可以接受，规范化结果不承诺保留原引用之间的别名关系。
+
+`canonicalizeJsonValue` 返回独立、递归冻结的 JSON 值；`canonicalizeJsonObject` 额外要求顶层为非数组对象。
+数值 `-0` 转换为 `0`。结果中的对象使用 **null prototype**，没有继承的对象方法；检查属性时使用
+`Object.hasOwn`，不要调用 `result.hasOwnProperty`。结果数组仍使用 `Array.prototype`。
+
+`CanonicalJsonPrimitive`、`CanonicalJsonValue` 和 `CanonicalJsonObject` 只描述静态数据结构，便于声明参数和结果。
+它们不是运行时验证凭证：例如普通 `number` 类型仍可表示 `NaN`，对象类型也不能证明数据已冻结、具有 null prototype
+或没有循环。有限数值和其它输入约束只能由规范化函数在运行时检查，不能通过类型标注或断言取得。
+
+### 确定性序列化
+
+`canonicalJsonText` 输出无额外空白的 JSON 文本。对象 key 按 JavaScript 字符串 `<` 比较的顺序排列，
+数组保留元素顺序，`-0` 输出为 `0`；字符串和其余基本值按 JSON 表示规则输出。
+`canonicalJsonBytes` 返回该文本的 UTF-8 编码。这些表示规则属于公开契约，不随内部重构任意改变；
+它们不承诺遵循其它 canonical-JSON 标准或执行 Unicode normalization。
+
+**规范化对象不是已序列化的规范文本。** `JSON.stringify` 对整数索引属性的枚举顺序不同：对于含 `"2"`、`"10"`
+两个 key 的对象，原生序列化先输出 `"2"`，`canonicalJsonText` 则先输出 `"10"`。需要上述确定性格式时，
+直接使用 `canonicalJsonText` 或 `canonicalJsonBytes`，不要以 `JSON.stringify(canonicalizeJsonObject(...))` 替代。
+
+## 闭合快照
+
+`snapshotExactClosedRecord(value, keys)` 要求顶层是非数组的 plain/null-prototype 对象，且自有 key 恰好匹配
+调用方提供的无重复 string 列表；所有自有属性必须是可枚举的数据属性。缺字段、多字段、symbol key、存取器属性或
+不可枚举属性都会被拒绝。`keys` 应由调用方持有并保持稳定；成功结果是使用 `Object.prototype` 的冻结浅副本。
+
+`snapshotClosedArray(value)` 要求使用 `Array.prototype` 的无空洞数组，除标准 `length` 与可枚举索引外没有其它
+自有属性，也没有存取器属性。成功结果是冻结的标准数组浅副本。
+
+两种快照均不检查字段值或元素的业务类型，也不要求它们是 JSON：函数、`undefined`、嵌套对象和引用可以保留。
+嵌套内容不会被复制或递归冻结，`-0` 不会被转换。浅副本固定的是外层结构，不是整棵数据的内容；
+需要独立 JSON 副本时选择规范化工具，不要把浅快照当作深层验证结果。
+
+## 执行与适用边界
+
+工具读取属性描述符，不调用输入的 getter 或 `toJSON` 方法。反射 Proxy 时仍可能执行其 trap；
+trap 抛出导致输入无法读取时，按所选工具的失败模型返回 `undefined` 或抛出 `TypeError`，不承诺隔离 trap 的副作用。
+这不是任意 JavaScript 对象的安全沙箱。
+
+这些工具不解析 JSON 文本，不替代领域 schema 或字段验证，也不提供签名、认证、保密性或文件系统权限控制。
+调用方按实际用途选择工具及失败处理，不必为了使用它们引入 Core 的运行生命周期。