@zxyycom/vibe-check 0.0.1 → 0.0.3

package/docs/guides/run-outputs.md

@@ -0,0 +1,171 @@
+# 配置 Run 输出与诊断
+
+需要调整终端显示、保存机器结果或排查一次 Run 时，先按目的选择输出，再配置本次覆盖、预览或日志目标。下文先说明常用配置，再说明如何读取输出状态和处理失败；Check facts 与 Run 分支的共同模型见 [API 机制](../api-mechanics.md#runresult-分支)。
+
+## 默认输出与本次覆盖
+
+`defineConfig` 默认启用 progress rendering 和 machine publication（目录 `artifacts/vibe-check`），关闭 diagnostic logging（默认目录 `.log/vibe-check`）。Definition 的 `outputs` 保存可复用默认值，RunControls 的 `outputs` 逐字段覆盖本次调用；省略或 `undefined` 不覆盖，`false`、数量 `0` 与 `formatter: null` 都有明确作用。即使关闭对应输出，提供的字段仍须通过 validation。参数归属见 [Definition 与 invocation](../api-mechanics.md#参数应该放在哪里)。
+
+## 常用配置
+
+先按目的选择字段。表中的 `outputs.*` 均可写入 Definition 作为默认值，也可写入 RunControls 只调整本次调用；其它字段只属于本次 Run。
+
+| 想做什么 | 设置什么 | 得到什么 |
+| --- | --- | --- |
+| 开关终端进度 | `outputs.progressRendering.enabled` | `true` 显示人读 lifecycle；`false` 关闭呈现，Check 仍正常执行与结算。 |
+| 调整每项明细数量 | `outputs.progressRendering.recordPreviewLimit`、`messagePreviewLimit` | 每个 settled row 默认分别最多显示 5 条；`0` 隐藏该类明细并保留省略数量。 |
+| 调整单条预览长度 | `outputs.progressRendering.textPreviewCodePointLimit` | 默认最多 240 个 Unicode code points；数值边界和 formatter 用法见下文。 |
+| 保存机器结果 | `outputs.machinePublication.enabled`、`directory` | terminal snapshot 形成后写入 machine files；稳定消费格式见[机器输出契约](../output.md)。 |
+| 开启排障日志 | `outputs.diagnosticLogging.enabled: true`，按需设置 `directory` | 为本次 Run 写入 core 与 scheduler 日志。 |
+| 保存终端进度副本 | RunControls 的 `progressLogFile` | 将相同的 terminal presentation 镜像到指定文件。 |
+| 在本次隔离目录中使用固定日志文件名 | RunControls 的 `diagnosticLogFileNaming: "channel"`，同时开启 diagnostic logging | 使用 `core.log`、`scheduler.log`；目录选择与冲突行为见[日志与输出目标](#日志与输出目标)。 |
+
+## Check messages 与受管 progress
+
+Check terminal `messages` 是有序的人读补充信息；consumer 仍按 outcome 处理 final data 和 Records。表中的两项 preview 数量必须为非负 safe integer，文本预算必须为正 safe integer；短预算时 `… [truncated]` 只保留放得下的 marker 前缀。accepted Records 与 final data 按各自的 `RunResult` / machine contract 保留，messages 保留在 `RunResult.checkMessages`；截断、formatter 或关闭呈现均不改写它们。
+
+在 callback 已等待的异步工作中通过全局 `console.*` 发出的文本，会作为该 Check 的 `console-<method>` messages 呈现。它适合短的人读诊断：不要向 console 写入 secret，也不要依赖 progress 文本保存完整事实。`process.stdout.write`、`process.stderr.write`、流式或 child-process 输出应写入 Check-owned file、transcript 或独立 logger；这些输出不具有可靠的 Check 归属，直接写入受管 terminal 也可能与 progress 交错。需要稳定补充说明时，在 terminal result 返回结构化 `messages`；从 Finding 生成有限摘要可用[呈现工具](presenting-findings.md)。
+
+### 配置 preview 文本
+
+需要在终端中保留长文本的前后片段时，把同步 `formatter` 写进 Definition。它接收冻结的 `{ kind, text, maxCodePoints }`：`kind` 是 `"record"` 或 `"message"`，`text` 是选中项未转义、未截断的默认正文（Record 为 local ID 加 canonical JSON，message 为正文），`maxCodePoints` 是当前文本预算。Product 仅对数量限制内的项调用一次，先 Records 后 messages；返回值仍由 Product 转义并限长。如下例把长文本折叠为头尾片段，并在本次 Run 单独缩小 Record 数量：
+
+```ts
+import {
+  defineCheck,
+  defineConfig,
+  run,
+  type ProgressPreviewFormatter
+} from "@zxyycom/vibe-check";
+
+const headAndTail: ProgressPreviewFormatter = ({ text, maxCodePoints }) => {
+  const points = [...text];
+  if (points.length <= maxCodePoints) return text;
+  const tailLength = Math.max(1, Math.floor(maxCodePoints / 3));
+  const headLength = Math.max(0, maxCodePoints - tailLength - 1);
+  return `${points.slice(0, headLength).join("")}…${points.slice(-tailLength).join("")}`;
+};
+
+const detail = defineCheck({
+  checkId: "detail",
+  displayName: "Detail",
+  execute: ({ records }) => {
+    records.report({ id: "long-detail" }, { text: "a verbose diagnostic value" });
+    return { status: "passed", data: {} };
+  }
+});
+
+const definition = defineConfig({
+  checks: [detail],
+  outputs: {
+    machinePublication: { enabled: false },
+    progressRendering: { formatter: headAndTail, textPreviewCodePointLimit: 48 }
+  }
+});
+
+const result = await run(definition, {
+  outputs: { progressRendering: { recordPreviewLimit: 1 } }
+});
+if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+```
+
+文本预算只限制转义后的 preview 正文（含截断 marker），不包含缩进、label、换行、汇总或省略提示；Unicode code points 不等于终端列宽或 graphemes。
+
+formatter 返回空字符串仍是一条呈现项；throw 或返回非字符串（包括 Promise/thenable）只使 `outputs.progressRendering` failed，不回退默认文本，也不改变 Check/Record/message facts。它是 trusted project code：可见完整默认文本，不能把预算当成 redaction/access control，Product 不 sandbox 其独立 I/O 或 detached work。`formatter: null` 可在 RunControls 明确清除 Definition formatter；省略或 `undefined` 不覆盖。Definition 的数值与 formatter 种类参与 declarative fingerprint，但函数 identity/source/closure 以及 RunControls 覆盖均不参与。
+
+## Progress rendering
+
+TTY 使用可更新的 running region；plain output 与 `TERM=dumb` 从不输出 running row，只追加
+settled presentation。每个可见 settled row 保留 measured duration 或 `not run`；完整、
+canonical-ordered `RunResult.checkDurations` 仍保留所有 Check，未执行项为 `null`。
+
+启用 `omitQuietPassedRow: true` 的 executable Check 在 TTY 中运行时仍可见，但 running row 与
+所有保留的 settled row 都使用无编号的 `· <name>` 格式。它安静通过时不写 settled row；安静
+通过是 `passed` 且 accepted Records/messages 均为空，final data、preview limit、formatter 文本和
+终端截断不改变这个判定。带 accepted detail 的通过，以及 `failed`、`not-applicable`、`unavailable`
+都保留为无编号 settled row，并继续使用既有 duration、reason、detail、escaping 和颜色规则。
+
+没有该策略的 row 继续显示 `[n/total]`。`n` 是全部 executable Checks 的全局 completion
+accounting：每次 settlement 都推进，即使对应 quiet-pass row 被省略，因此保留的普通 row 可以跳号；
+它不是可见结果行的 ID。flag-condition-not-matched 仍按既有 Definition 顺序进入原因聚合块，
+不形成 running row；该聚合优先于 quiet-pass 省略。
+
+至少一个 normalized executable Check 启用该策略时，header 精确追加
+`· <configured> configured for quiet-pass omission`，例如 `total 12 checks · 3 configured for quiet-pass omission`。
+这里的 `configured` 是静态声明数，包含本次因 flags 未匹配而未启动的 Check。final summary 在
+既有 `elapsed` 前精确追加 `quiet-pass rows omitted: <actual>`；`actual` 只计 renderer 实际省略的
+quiet pass，不计 flag mismatch、未完成的潜在省略或任一保留 row。因此两个数可以不同。没有
+configured Check 时，header、final summary、terminal 与 progress tee 的既有 bytes 保持不变。
+
+flag control barrier 结束后，因 `enabledByFlags` 未匹配而未启动的 Checks 以一个原因块分组呈现，而非逐项 settled row；dependency activation 带入的 Check 不在该组。两种显示压缩都不改变 Check facts、accounting 或结果。配置 `progressLogFile` 时，同一 rendered bytes 先写 terminal、再写 file；file setup/write/close failure 使 progress output failed，但不吞掉 terminal presentation。
+
+这项呈现策略不新增或改写 `RunResult`、machine schema 或 Check lifecycle facts；它只改变人读
+row 的保留和编号格式。当前已发布版本的 [changelog](../changelog.md) 历史不由这项规则改写；
+升级说明由相应发布变更按实际版本净差异维护。
+
+## 日志与输出目标
+
+machine publication 与 diagnostic logging 的 `directory` 都是调用方选择的非空、无 U+0000 的受信任 target：相对路径从 effective `projectRoot` 解析，绝对路径直接使用；它们不提供 containment 或 sandbox 语义。`progressLogFile` 使用相同的路径规则。
+
+diagnostic logging 为当前 invocation 写入人工诊断。它用于关联 Run、Check、phase 与 Scheduler 行为；日志不是 parser/schema、跨 invocation discovery 或 retention contract，也不替代 Check final data、Record 或 message。
+
+diagnostic 文件默认使用 `core-<utc-compact>-<uuid>.log` 与 `scheduler-<utc-compact>-<uuid>.log`。调用方已有隔离的 invocation 目录时，可以在 controls 同时设置 `diagnosticLogFileNaming: "channel"` 与 `outputs.diagnosticLogging: { enabled: true, directory: "<本次目录>" }`，得到 `core.log` 与 `scheduler.log`，不额外创建目录层级。Product 不保证该目录独占：每 channel 始终 exclusive-create，冲突即 failed，不覆盖、追加或退回唯一名；两个 channel 不是原子事务，一个失败时另一个仍可成功。从 channel `file` 读取实际目标；命名选项只控制文件名；日志内容保留 invocation ID、共享 sequence 与 elapsed-time correlation 信息。
+
+启用 diagnostic logging 时，scheduler channel 可给出本次 Run 的 `scheduler.summary`：它帮助解释 admission、等待、capacity 与 tail 的当前诊断投影。time 与 capacity 指标只描述 Scheduler 行为，不表示 CPU、memory、thread 或 process 的 OS utilization；需要 machine-readable 结论时，仍读取 machine output 和 Check facts。
+
+## 排查输出配置错误
+
+本次 `outputs` 覆盖值不合法时，Run 在执行 Check 或创建输出前返回 `kind: "configuration"`。
+先检查 `diagnostic.kind === "invalid-run-controls"`，再按 `path` 定位本次 controls 中的字段。
+`reason: "unknown-key"` 表示应删除或更正该字段名；`reason: "invalid-value"` 时，输出覆盖值诊断还提供
+`expected` 说明合法值要求。例如 `recordPreviewLimit: -1` 返回：
+
+```json
+{
+  "kind": "invalid-run-controls",
+  "path": "controls.outputs.progressRendering.recordPreviewLimit",
+  "reason": "invalid-value",
+  "expected": "non-negative-safe-integer"
+}
+```
+
+| `expected` | 合法值要求 |
+| --- | --- |
+| `plain-data-object` | 普通或 null-prototype 对象，只含可枚举的自有字符串 data properties；不能使用数组、accessor 或 symbol key。 |
+| `boolean` | `true` 或 `false`。 |
+| `function-or-null` | formatter 函数或 `null`；函数的同步返回要求见[preview 配置](#配置-preview-文本)。 |
+| `non-negative-safe-integer` | 大于等于 `0` 的安全整数。 |
+| `positive-safe-integer` | 大于 `0` 的安全整数。 |
+| `non-empty-string-without-nul` | 非空且不含 U+0000 的字符串；路径规则见[日志与输出目标](#日志与输出目标)。 |
+
+即使对应输出已关闭，显式提供的字段仍须合法。对象本身无法安全读取时，`path` 指向该对象，不尝试执行
+getter 来寻找更深字段。诊断不回显被拒绝的值；unknown key 诊断不提供 `expected`，其它 controls 诊断也可能
+省略它。Definition 的无效输出配置仍通过 `invalid-project-definition` 指向 `definition.outputs`。
+
+## 输出状态与失败处理
+
+只有 non-configuration `RunResult` 具有有效 output configuration 与 `outputs` readback。每项 status 使用 `"disabled" | "not-run" | "succeeded" | "failed"`。`RunResult.outputs.progressRendering` 返回 `{ enabled, status }`；预览文本、effective limits 与 formatter 由配置和呈现流程使用，不包含在返回值中。
+
+channel setup、write 或 close failure 只使对应 output failed，不改写已经形成的 Check/Record facts，也不阻断其它 output 结算。
+
+`checkAggregation` 不是 output formatter，也不产生 output status。它在完整 Check settlement 后、正常 final progress summary 与 machine publication 前同步解释有效 Check 列表。若该函数抛错、返回 Promise/thenable 或非法四态值，`run(...)` 直接拒绝：Product 会关闭本次 diagnostic/progress writer，但不呈现正常成功 summary、不发布正常 machine result，也不返回可读取 output status 的 `RunResult`。调用方应处理这个 Promise rejection；它不能靠 `kind: "output"` 恢复。
+
+当 primary Run 已正常完成时，output failure 使结果成为 `kind: "output"`；多个 failure 依次选择 progress rendering、machine publication、diagnostic logging、terminal effects 的第一个作为 diagnostic。`scheduler-terminal-effects-failed` 因而只表示 terminal effect 是按该顺序选中的 failure；cancellation 或 execution diagnostic 保持原有 primary result，terminal-effect failure 仍在 `outputs.terminalEffects.status` 可见。
+
+### Diagnostic channel 状态
+
+`outputs.diagnosticLogging` 的形状为 `{ enabled, status, channels }`，其中 `channels` 是 `core`、`scheduler` 的 `{ enabled, status, file }` map。禁用 channel 的 `file` 为 `null`；启用 channel 即使创建文件失败也保留预先计算的 `path.relative(projectRoot, resolvedFile)`，因此 root 外 target 可含 `..`，跨卷时平台可以返回 absolute path。任一 enabled channel failed 时 aggregate status 为 `failed`，只有全部 enabled channel succeeded 时为 `succeeded`。
+
+### Terminal effect 状态
+
+`scheduler.terminalEffects` 在 Definition 中配置，不能由 RunControls 注入或覆盖。终态观察交付给调用方配置的 Definition effects 与 prepared strategy 的 public `terminalEffect`；调用顺序和 context 见[调度专题](scheduling.md#交付终态-measurement)。
+
+`outputs.terminalEffects` 的形状为 `{ enabled, status }`：
+
+| 条件 | `enabled` / `status` |
+| --- | --- |
+| normalized `scheduler.terminalEffects` 非空，或 successful prepared strategy 实际提供 `terminalEffect` | `enabled: true`。 |
+| 两者都没有 | `enabled: false`，`status: "disabled"`。 |
+| enabled Run 没有 sealed terminal sequence | `status: "not-run"`。 |
+| sealed sequence 中所有 Definition effects 与可选 public `terminalEffect` 都成功 | `status: "succeeded"`。 |
+| 任一 Definition effect 或 `terminalEffect` throw/reject | `status: "failed"`；后续 `terminalEffect` success 不会覆盖已记录的 Definition-effect failure。 |

package/docs/guides/scheduling.md

@@ -0,0 +1,208 @@
+# 按项目约束调度 Check
+
+本专题面向已经有多个自定义 Check、需要表达并发约束、改变 ready task 的选择顺序的调用方。默认 `{ kind: "static" }` 已经遵守依赖、mutex、root/scoped 并行预算、named resource capacity 和取消；只有这些不变式之外的**选择偏好**需要项目规则时，才使用 custom policy（包括 learned helper 返回的 prepared strategy）。Check 自己的 options、preparation、execution 与取消处理见[编写自定义 Check](extending-check-lifecycle.md)。
+
+## 选择正确的工具
+
+| 目标 | 使用 | 作用边界 |
+| --- | --- | --- |
+| 让一组 Task 互斥执行 | 在每个相关 Check 的 `mutex` 写入同一个名称 | 同一互斥名称下，同一时刻最多运行一个 Task。 |
+| 为可计数共享资源声明并发容量 | `scheduler.resourceCapacities` 与 Check 的 `resourceClaims` | capacity 与 claim 都是本次 Run 的静态 units。 |
+| 只指定静态相对顺序 | Check 的 `admissionPriority` | 在 Scheduler 的 relation、mutex、容量和取消约束内排序 ready Task。 |
+| 每次 ready selection 根据当前事实选择一个 task | `scheduler.admissionPolicy` 的 `custom/simple` strategy | 向 Scheduler 提交一个 selection proposal。 |
+| 先异步准备本 Run 专用决策 closure，或在终态 measurement 后收尾 | `custom/prepared` strategy | `prepare` 形成 Run-local closure，`terminalEffect` 消费 terminal measurement。 |
+| 对独立静态图比较假设分支 | [`createAdmissionGraph(...)`](simulating-admission.md) | 不执行 Check；在独立专题中建立并比较 immutable successor。 |
+| 多次运行后按本地时长历史改善选择 | `createLearnedCriticalPathStrategy(...)` 作为 `custom/prepared` strategy | 使用调用方管理的本地 history 形成选择偏好。 |
+| Run 结束后保存项目自己的调度统计 | `scheduler.terminalEffects` | 接收冻结的 terminal measurement 作为 side effect 输入。 |
+
+`admissionPriority` 必须是有符号 safe integer；Check 节点省略时继承最近显式祖先值，没有祖先声明时为 `0`。
+
+## 限制 named resource 并发
+
+`scheduler.maxParallel` 限制同时运行的 Check 总数，必须是正 safe integer，`defineConfig` 省略时默认 `4`。Check 节点的 `maxParallel` 也必须是正 safe integer，省略时继承最近显式祖先值；没有祖先声明时使用 root 预算。除表中的 `mutex` 外，需要让不同 Check 消耗同一种资源的不同 units 时，配置静态 named resource capacity：
+
+```ts
+import { defineCheck, defineConfig } from "@zxyycom/vibe-check";
+
+const firstAudit = defineCheck({
+  checkId: "first-audit",
+  displayName: "First audit",
+  mutex: ["exclusive-audit"],
+  resourceClaims: { worker: 1, capacityUnits: 2 },
+  execute: () => ({ status: "passed", data: {} })
+});
+
+const secondAudit = defineCheck({
+  checkId: "second-audit",
+  displayName: "Second audit",
+  mutex: ["exclusive-audit"],
+  execute: () => ({ status: "passed", data: {} })
+});
+
+export default defineConfig({
+  checks: [firstAudit, secondAudit],
+  scheduler: {
+    maxParallel: 4,
+    resourceCapacities: { worker: 2, capacityUnits: 8 }
+  }
+});
+```
+
+两个 Check 共享 `exclusive-audit`，因此同一时刻最多运行其中一个；它们仍可分别声明不同的 resource claims。resource ID 必须是非空白字符串，capacity 和 claim 都必须是正 safe integer。每个 claim 必须引用已声明资源且不大于其总 capacity，否则 Definition 在任何 Check work 前失败。一个 Task 的全部 claims 在 admission 时原子取得，并在任意 settlement（成功、失败或其它终态）后一起释放；Scheduler 不会先占一部分再等待另一部分。同一 ordinary selection layer 中，没有 claim 的 ready work 仍可使用空闲 root slot，不会因为另一个 Task 正等待 named resource 而被扣留；既有 tighter-scope activation/continuation 层级仍先于 ordinary work。
+
+`resourceClaims` 与 `maxParallel`、relations 和 mutex 一样可写在 container 上供 descendants 继承；省略保留最近的完整 mapping，显式 `{}` 清空，任何其它显式 mapping 都完整替换而不与父 mapping 合并。named resources 是 invocation-local 静态计数；`mutex` 表达逻辑组互斥，`resourceClaims` 表达 units 容量，两者可以按项目约束组合。
+
+## 自定义准入 policy
+
+`decide(context)` 读取 frozen 的 graph、候选和 immutable `admissionState`，只返回 `{ kind: "select", taskId }` 或 `{ kind: "wait" }`。Scheduler 独占 readiness、mutex、容量、Task 启动与结算；策略只能提出 proposal，不能保证 proposal 会被接受。
+
+```ts
+import { defineAdmissionPolicy, defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+const executionOrder: string[] = [];
+
+const compile = defineCheck({
+  checkId: "compile",
+  displayName: "Compile",
+  execute() {
+    executionOrder.push("compile");
+    return { status: "passed", data: {} };
+  }
+});
+
+const publish = defineCheck({
+  admissionPriority: 10,
+  checkId: "publish",
+  dependsOn: [compile.checkId],
+  displayName: "Publish",
+  execute() {
+    executionOrder.push("publish");
+    return { status: "passed", data: {} };
+  }
+});
+
+const preferPublish = defineAdmissionPolicy({
+  kind: "custom",
+  strategy: {
+    kind: "simple",
+    decide(context) {
+      const publishTask = context.graph.tasks.find((task) => task.taskId === publish.checkId);
+      const publishCandidate = context.candidates.find(
+        (candidate) => candidate.taskId === publish.checkId && candidate.canAdmit
+      );
+      if (publishTask?.admissionPriority === 10 && publishCandidate !== undefined) {
+        return { kind: "select", taskId: publishCandidate.taskId };
+      }
+
+      const nextCandidate = context.candidates.find((candidate) => candidate.canAdmit);
+      return nextCandidate === undefined
+        ? { kind: "wait" }
+        : { kind: "select", taskId: nextCandidate.taskId };
+    }
+  }
+});
+
+const definition = defineConfig({
+  checks: [compile, publish],
+  outputs: {
+    diagnosticLogging: { enabled: false },
+    machinePublication: { enabled: false },
+    progressRendering: { enabled: false }
+  },
+  scheduler: {
+    admissionPolicy: preferPublish,
+    maxParallel: 1
+  }
+});
+
+const result = await run(definition);
+if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+if (executionOrder.join(",") !== "compile,publish") {
+  throw new Error(`Unexpected execution order: ${executionOrder.join(",")}`);
+}
+```
+
+`decide` 必须同步且给出合法、可 drain 的 proposal。throw、thenable、malformed/illegal proposal 或不可 drain 的 `wait` 会产生 `admission-policy-failed`：Scheduler 停止新的 admission、取消 pending work 并等待已启动 work。这个 invocation failure 不是任一 Check outcome。
+
+### 在线选择时读取 observation prefix
+
+custom `decide(context)` 可通过 `context.measurement` 读取当前 decision boundary 已冻结的**观察前缀**：
+
+- `cumulative` 提供当前累计的离散计数、peaks 和 timing availability；只有 `timing.availability === "available"` 才有 `timingFacts`。
+- `measurementCount` 是当前已捕获 action observation 的数量。
+- `measurementAt(index)` 只读取这个 context 冻结的 prefix；`0 <= index < measurementCount` 之外返回 `undefined`。每项说明上一次 accepted `select` 或 `wait` 后的 effects 与 interval，不声明某个 action 导致了时长、critical path 或 CPU 使用。
+
+用它在**在线选择**时比较当前累计事实；不要把它当作完整逐 Task 历史或终态报告。需要 Run 结束后的完整 graph、settled tasks 与 raw measurement，改用下面的 `scheduler.terminalEffects`；prepared strategy 的 `terminalEffect` 同样只在有 terminal measurement 时运行。
+
+## 已准备的 custom strategy
+
+需要在 Scheduler 开始前异步读取调用方自己的配置，并把结果形成本 Run 专用 decision closure 时，使用 `{ kind: "prepared", prepare }`。每个 graph-ready Run 最多调用一次 `prepare`；它返回同步 `decide` 和可选的 `terminalEffect(terminal)`。下例优先选择可准入的 `second`，否则选择第一个可准入候选，并在 `terminalEffect` 中保存终态任务计数：
+
+```ts
+import { defineAdmissionPolicy, defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+let settledTaskCount: number | null = null;
+
+function scheduledCheck(checkId: string) {
+  return defineCheck({
+    checkId,
+    displayName: checkId,
+    execute: () => ({ status: "passed" as const, data: {} })
+  });
+}
+
+const strategy = defineAdmissionPolicy({
+  kind: "custom",
+  strategy: {
+    kind: "prepared",
+    async prepare() {
+      // 模拟异步读取调用方自己的配置，并将其捕获在本 Run 的 closure 中。
+      const preferredTaskId = await Promise.resolve("second");
+      return {
+        decide(context) {
+          const next = context.candidates.find(
+            ({ canAdmit, taskId }) => canAdmit && taskId === preferredTaskId
+          ) ?? context.candidates.find(({ canAdmit }) => canAdmit);
+          return next === undefined
+            ? { kind: "wait" as const }
+            : { kind: "select" as const, taskId: next.taskId };
+        },
+        terminalEffect(terminal) {
+          settledTaskCount = terminal.execution.settledTasks.length;
+        }
+      };
+    }
+  }
+});
+
+const definition = defineConfig({
+  checks: [scheduledCheck("first"), scheduledCheck("second")],
+  outputs: {
+    diagnosticLogging: { enabled: false },
+    machinePublication: { enabled: false },
+    progressRendering: { enabled: false }
+  },
+  scheduler: { admissionPolicy: strategy }
+});
+
+const result = await run(definition);
+if (result.kind !== "completed" || settledTaskCount !== 2) {
+  throw new Error("Expected a completed Run and terminal measurement for both Checks");
+}
+```
+
+策略需要的配置、logger 或 clock 由调用方提供并捕获在 closure 中；context 只提供调度事实，真实 Task 启动与结算由 Scheduler 控制。准备失败与终态收尾边界如下。
+
+### 交付终态 measurement
+
+任何 scheduler policy 都可配置 `scheduler.terminalEffects`。每个 effect 在 Scheduler 已有 terminal measurement 后收到冻结的 `{ graph, execution, rawMeasurement }`；它适合调用方自己的统计、记录或后续处理，不能修改 Task、Check facts、aggregate 或选择历史。若同时配置 Definition effect 与 prepared `terminalEffect`，Definition effects 先结算，随后才调用 `terminalEffect`。如果任一 effect 或 `terminalEffect` 抛错或 reject，`result.outputs.terminalEffects.status` 为 `failed`；Check facts 不变，原本正常完成的 Run 可映射为 `kind: "output"`，已有 `cancelled` / `execution` 主结果保持不变。
+
+终态 measurement 不同于 `decide` 所读 `context.measurement` 的在线观察前缀。需要逐项业务数据、失败原因或 Records 时，在 Check 的 `execute` 中形成事实，再从 `RunResult` 读取。
+
+`prepare` 只在 graph 已有效且 Run 尚未于 pre-work / planning 取消后调用；它没有 cancellation signal、timeout 或“必有 terminalEffect”的 cleanup 保证。prepare reject 会结束为 `admission-strategy-preparation-failed`。一旦 Run 进入 Scheduler，正常结束、取消或 policy fault 的 drain 只要 seal 出 terminal measurement，都会在 Definition effects 后调用 `terminalEffect`；早期 setup / execution failure 没有 terminal measurement 时不会调用它。因此不要在 `prepare` 中取得必须依赖 `terminalEffect` 释放的资源。
+
+保存后续 Run 会使用的 caller-owned data 时，先根据自己的目标定义“可接受样本”。`rawMeasurement.timing.availability === "available"` 只证明终态 timing facts 可读，不证明 Run quality 成功；`settledTasks.kind === "completed"` 是 Scheduler settlement，不等于 Check `passed`，且 context 不提供 `RunResult.kind`。若业务只允许成功 Run，先暂存候选，在 `run(...)` 返回后同时核对 `result.kind` 与业务要求的 Check outcomes 或 aggregate，再决定是否提交。`kind: "completed"` 本身不表示质量检查全部通过。
+
+## 复用本地时长历史
+
+同一项目反复运行、希望依据历史时长安排 ready Tasks 时，阅读[用本地时长历史调度 Check](learned-scheduling.md)。该专题说明 `createLearnedCriticalPathStrategy`、caller-owned history 与观察回调。

package/docs/guides/simulating-admission.md

@@ -0,0 +1,55 @@
+# 比较假设调度分支
+
+用 `createAdmissionGraph(...)` 分析独立静态图，不必定义或执行真实 Check。真实 Run 的并发约束和准入 policy 见[调度 Check](scheduling.md)。
+
+## 模拟 AdmissionGraph
+
+`createAdmissionGraph({ graph, maxParallel })` 接收已规范化的 `SchedulerGraphSnapshot`，不是 Definition 的 scheduler 配置；`maxParallel` 必须是正 safe integer。构图时验证完整字段和引用，无效输入抛错。
+
+```ts
+import { createAdmissionGraph } from "@zxyycom/vibe-check";
+
+const graph = createAdmissionGraph({
+  graph: {
+    resourceCapacities: [{ resourceId: "browser", units: 1 }],
+    scopes: [],
+    tasks: [
+      {
+        admissionPriority: 0,
+        dependsOn: [],
+        mutex: [],
+        observes: [],
+        resourceClaims: [{ resourceId: "browser", units: 1 }],
+        scopeId: null,
+        taskId: "compile"
+      },
+      {
+        admissionPriority: 0,
+        dependsOn: ["compile"],
+        mutex: [],
+        observes: [],
+        resourceClaims: [],
+        scopeId: null,
+        taskId: "publish"
+      }
+    ]
+  },
+  maxParallel: 1
+});
+
+const initial = graph.initialState();
+const compile = initial.select("compile");
+if (!compile.accepted) throw new Error(`Cannot select compile: ${compile.reason.kind}`);
+
+// Retaining `initial` and the successor forms two independent hypothetical branches.
+const completed = compile.state.settle("compile", "satisfied");
+if (!completed.accepted || !completed.state.catalog.selectableTaskIds.includes("publish")) {
+  throw new Error("Expected publish to become selectable after hypothetical completion");
+}
+```
+
+`select` / `settle` 成功时返回新的 immutable `state`，保留原 state 即可分支；拒绝时返回 `{ accepted: false, reason }`，没有 successor。模拟不启动真实 Check、不预留真实资源，也不写回 Run。
+
+只有 running Task 可 `settle`：`satisfied` 满足其 `dependsOn` 下游的这项前置；`unsatisfied` 使未满足前置的下游被阻止并结算，不能再选择。`observes` 只等待终态，不要求 satisfied。例如，从同一 `compile.state` 改用 `settle("compile", "unsatisfied")`，`publish` 就不会变为可选。
+
+输入 graph 的 named resource capacities/claims 使用 canonical `{ resourceId, units }[]`；successor inspection 投影当前 `{ capacity, inUse, available }`，不提供 reservation 或真实资源 handle。

package/docs/output.md

@@ -31,7 +31,9 @@ Check-local parser。
 也启用，二者共享该 instant。两项 output 都禁用时，Run 不读取或序列化 wall clock。每个 Check row 包含
 `checkId`、`displayName` 和一种 terminal outcome：`passed` / `failed` 带 object-shaped final `data`；
 `not-applicable` / `unavailable` 带受控 reason，前者可以省略 reason。Aggregation、所有 Run output status 与
-diagnostic logging file、duration、terminal messages、visibility 和 progress presentation 不属于 machine fields。
+diagnostic channel files、duration、author terminal messages、Product-captured Check console messages、
+`omitQuietPassedRow` 人读呈现策略和 progress presentation 不属于 machine fields。quiet-pass row 的省略、
+无编号格式及 configured/actual 计数都不改变 terminal Check facts 或 v4 publication。
 
 每个 `records.ndjson` row 的结构是：
 
@@ -57,13 +59,12 @@ own-key enumeration 与序列化时的 key 排列也不是 public contract。
 
 Publisher 在修改 canonical paths 前先形成并完整验证两份文件。写入或首次 canonical rename 失败时保留 prior set；一次
 canonical replacement 已发生后的 handled failure 会清理可能混合的 canonical files。pre-work configuration failure
-不进行 output I/O。diagnostic logging 是独立的人读 Run output，不进入 v4 directory、schema、example 或 publication set；
-machine consumer 不发现或解析它。其 configuration 与 `RunResult` readback 见
-[深入 API 机制](api-mechanics.md#outputs-与-runresult-边界)。
+不进行 output I/O。machine directory 是调用方选择的受信任 target，不是 containment/sandbox；publisher 只拥有其中的两个 canonical files 及其私有临时文件，绝不清空整个目录。diagnostic logging 是独立的人读 Run output，由 core 和 scheduler channel files 组成；即使调用方为它选择同一目录，它也不进入 v4 schema、example 或 publication set，machine consumer 不发现或解析它。其 configuration 与 `RunResult` readback 见
+[Run 输出与诊断](guides/run-outputs.md#输出状态与失败处理)。
 
 两个 canonical files 是独立 filesystem paths，rename 不提供跨路径原子可见性。并发 reader 可能观察到 mixed
 generation，因此必须按完整集合执行 fingerprint validation；需要 generation pointer、reader lock 或跨路径 atomic
-visibility 的系统，应在 Vibe Check 契约之外建立自己的读取协议。
+原子可见性的系统，应在 Vibe Check 契约之外建立自己的读取协议。
 
 ## 随包材料与版本
 
@@ -76,22 +77,13 @@ visibility 的系统，应在 Vibe Check 契约之外建立自己的读取协议
 | [`run.json`](examples/artifacts/mixed-outcomes/run.json) | 与该 Definition 的五个可执行 Check 对应，集中展示 package-provided/custom `passed`、`failed`、`not-applicable` 与 `unavailable` facts。 |
 | [`records.ndjson`](examples/artifacts/mixed-outcomes/records.ndjson) | failed policy 发布的两条 supplemental Records，用于核对多行 framing、ownership、排序和 fingerprint。 |
 
-这三份材料按以下关系阅读：
-
-1. `jsonValidation({ files: { include: ["package.json"] } })` 使用随包 constructor，显式选择 `package.json` 并保留默认
-   source / exclude policy；示例输入中的有效 manifest 使 `json-validation` 形成 `passed` final data。
-2. `example-release-inputs` 的 preflight 在 authored files 为空时以 `failure / continue` 准备 fallback，再由
-   `parseData` 声明 typed provider contract；对应 Check 形成 `passed`。
-3. 递归 `example-release-workflow` 把 manifest dependency 传给 children；`example-release-policy` 用 `inherit` 追加 provider
-   dependency，读取并解析两份 upstream final data，随后形成 `failed` final data 和两条 Records。组织节点自身不产生 Check row。
-4. optional Check 直接形成 `not-applicable`；external review 的 `failure / block` preflight 在任何 execution 开始前形成
-   `unavailable`。两条 preflight message 与 failed policy message 保留在 `RunResult.checkMessages`，不进入 machine fields。
-
-仓库生成器通过完整 public `run` 执行同一份 Definition，并使用只含有效 `package.json` 的隔离 project root 得到以上
-Check/Record facts；随后只把 invocation ID 与 timestamp 固定为文档值，使 checked-in bytes 可重复生成。示例 Definition
-启用了 `artifacts/vibe-check` machine publication；直接运行会在本次 project root 下更新该目录中的两份 canonical files。
-示例 facts 与固定 metadata 只用于核对 Definition/output 对应关系；consumer 在自己的 project root 调用
-`run(definition)` 时，会按实际 `package.json` 形成结果和本次 Run 的 invocation metadata。
+示例的输入与结果可按三条路径核对：
+
+- `jsonValidation` 显式检查 `package.json`，保留默认 source/exclude；自定义 provider 在空 authored files 时以 preparation fallback 继续并通过。
+- 递归 workflow 继承 manifest dependency；policy 用 `inherit` 追加 provider，解析两份 upstream data，再形成 failed data 与两条 Records。container 不产生 Check row。
+- 另两项分别直接 `not-applicable` 与被本项 preparation block 为 `unavailable`，不阻挡无 relation 的其它 Check。preparation 和 policy messages 仅进入 `RunResult.checkMessages`。
+
+checked-in outputs 在只含有效 `package.json` 的隔离 root 中执行该 Definition 后生成，仅把 invocation ID 与 timestamp 固定为文档值。直接 `run(definition)` 会根据你的实际 `package.json` 形成结果和本次 metadata，并更新 project root 下 `artifacts/vibe-check` 中的两份 canonical files；示例 facts 不是对任意项目结果的保证。
 
 随包机器契约的当前版本是 v4，validation boundary 对其它 schema identity fail closed。本示例使用非空 Record set；零
 Record 集合按读取规则表示为零字节 `records.ndjson`。

package/licenses/Lizard-1.24.0-MIT.txt

@@ -0,0 +1,30 @@
+Copyright Terry Yin and other contributors
+
+This software consists of voluntary contributions made by many
+individuals. For exact contribution history, see the revision history.
+
+The following license applies to all parts of this software except as
+documented below:
+
+====
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+====

package/{third-party-licenses/momoa-3.3.12-LICENSE → licenses/Lizard-1.24.0-lizard.py-Apache-2.0.txt}

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/

package/licenses/Pygments-2.18.0-BSD-2-Clause.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2006-2022 by the respective authors (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/licenses/analyzer-translations-NOTICE.md

@@ -0,0 +1,24 @@
+# Incorporated Analyzer Source Notices
+
+This directory contains the third-party source material incorporated into Vibe Check's
+Function Metrics analyzer. This notice describes only those translated sources.
+
+## Lizard 1.24.0
+
+Vibe Check contains modified TypeScript translations of source ranges from
+[terryyin/lizard](https://github.com/terryyin/lizard), fixed at revision
+`308b1c3efd8c1c69bcc3eb82deeaec64fd3662ec`. The exact source ranges, target paths,
+and SPDX identities are recorded in [lizard-1.24.0-provenance.json](lizard-1.24.0-provenance.json).
+The translated source headers identify their originating source and modification status.
+
+- The translated Lizard source is covered by the complete
+  [Lizard MIT text](Lizard-1.24.0-MIT.txt).
+- Translated ranges from `lizard.py` are covered by the complete
+  [Apache-2.0 text](Lizard-1.24.0-lizard.py-Apache-2.0.txt).
+
+## Pygments 2.18.0 Erlang lexer
+
+The Erlang reader also contains a modified TypeScript translation of the recorded
+`pygments/lexers/erlang.py` range from Pygments 2.18.0. Its source header and the
+provenance inventory identify that BSD-2-Clause material; the complete text is
+[Pygments-2.18.0-BSD-2-Clause.txt](Pygments-2.18.0-BSD-2-Clause.txt).