@zxyycom/vibe-check 0.0.1 → 0.0.3

package/docs/api-mechanics.md

@@ -1,6 +1,6 @@
 # 深入理解 Vibe Check API 机制
 
-本文说明 package 的通用 invocation lifecycle：自定义 Check 如何经过 Definition validation、options preflight、execution 与 settlement，以及一次 Run 如何形成 dependency data、aggregation、outputs 和可判别结果。首次集成先阅读[package README](../README.md)；随包 Check 的 options、业务效果和安全边界由各自指南说明；单个 public 字段与函数签名以 installed declarations 为准。
+本文说明 package 的通用 invocation lifecycle：自定义 Check 如何经过 Definition validation、options preparation、execution 与 settlement，以及一次 Run 如何形成 dependency data、aggregation、outputs 和可判别结果。首次集成先阅读[package README](../README.md)；随包 Check 的 options、业务效果和安全边界由各自指南说明；单个 public 字段与函数签名以 installed declarations 为准。
 
 ## 一次 Run 的生命周期
 
@@ -12,131 +12,152 @@
     Project Definition
       │ run: validate Definition + RunControls, then normalize the Check tree
       ▼
-    declarative snapshot + fingerprint + complete static graph validation
-      │ sequential all-Check preflight barrier
+    validated Definition + normalized Check tree
+      │ before work: stop if cancelled; otherwise validate the complete static graph
       ▼
-    prepared Checks / blocked unavailable outcomes
-      │ build the ready task graph; apply dependency, mutex and parallel scheduling
+    complete static graph
+      │ when configured: prepare one Git change snapshot and derived flags
+      │ recheck cancellation, prepare the admission strategy, then form effective flag selection
+      ▼
+    initial control settlements + complete static Task graph
+      │ Scheduler applies direct relations, mutex and parallel scheduling
+      ▼
+    task-local preparation / Product-owned blocked unavailable outcomes
+      │ admitted Checks continue to author callback
       ▼
     author execution + terminal settlement
       ▼
     snapshot + messages + durations
-      │ optional aggregation + enabled output completion
+      │ terminal effects settle; if terminal context exists, prepared strategy delivers terminalEffect once
+      │ default or caller-local aggregation + enabled output completion
       ▼
     RunResult
 
-Run 在 preflight 前验证包含全部可执行 Check 的静态 task graph；完整 barrier 结束后，blocked Check 先结算为
-`unavailable`，其余 prepared Checks 再形成 ready task graph。Run snapshot 保存 Check facts；progress rendering 呈现
-execution lifecycle；machine publication 在 terminal snapshot 形成后写入 machine files。所有 author execution 都在完整
-preflight barrier 之后开始，optional aggregate 也在 terminal facts 结算后计算。
+### Selection 与 Scheduler readiness
 
-## Definition 与 invocation 的责任
+Run 先验证 Definition 与 Controls 并规范化 Check tree；若 signal 已取消，会在静态 graph validation 和获取 Git 前结束调用。否则 Product 验证包含全部可执行 Check 的静态 graph。Definition 配置 `changes` 时，Product 随后只取得一次 Git changed-path snapshot，按声明 region 生成受保护的 `vibe-check:change:<id>` flags；可信零命中保留空 evidence，获取失败保留 unavailable evidence 并保守提供所有已声明 change flags。再次检查 cancellation 后，caller/derived flags 共同形成一次 private effective selection。[flag 规则](guides/extending-check-lifecycle.md#按-flag-选择-check)定义其条件；未被选择项先结算为 `not-applicable / flag-condition-not-matched`，不会再次 admission。它们仍属于同一张 graph：`dependsOn` dependent 在 preparation 前结算为 `unavailable / dependency-not-passed`，`observes` consumer 则可等待并读取该终态。
 
-- `defineCheck(value)` 保留 literal `checkId`、options 和 typed-provider parser 的 TypeScript inference。它与同 shape 普通 Check object 具有相同 runtime 语义。
-- `defineConfig(value)` 形成带默认 `apiVersion`、outputs 和 scheduler policy 的 Project Definition。
-- `run(definition, controls?)` 拥有 invocation validation 与 normalization：它关闭递归 Check grammar，detach / canonicalize authored options，并形成 declarative snapshot 与 fingerprint。
+### Task-local preparation 与 execution
 
-fingerprint 使用 normalized declarative fields；preflight 与 execution callbacks 保持为执行行为。同一份 Definition 可以重复调用，每次 Run 都从 authored input 派生自己的 project context、prepared options、terminal facts 和 output statuses。
+其余 Check 被 Scheduler 在 direct relation、mutex 与 capacity 允许后 admission，并在自己的 task 中执行 preparation，随后才执行 author callback。没有互相约束的 preparation 可以并行；它们不构成 Definition 顺序的全局 barrier。
 
-## options preflight 与 execution
+### Terminal snapshot、aggregation 与 outputs
 
-可执行 Check 可以提供 `preflight(options, signal)`，在 author execution 前准备本次 invocation 使用的 options。authored 与 prepared options 同形时可以直接使用 authored options；两种 shape 不同时，TypeScript 要求提供 preflight。
+Run snapshot 保存所有 Check facts；progress rendering 呈现 execution lifecycle；machine publication 在 terminal snapshot 形成后写入 machine files。aggregation 在完整 terminal facts 结算后、正常 final progress 和 machine publication 前，读取本次有效 Check 列表；默认或 caller-local 函数都不改写 snapshot。
 
-preflight 返回以下三种 closed result 之一：
+prepared strategy 的 `prepare / decide / terminalEffect` 顺序、失败与取消边界由[调度专题](guides/scheduling.md#已准备的-custom-strategy)定义；这些回调不能回写已结算 Check facts。
 
-| 结果 | execution 输入与 Check outcome |
-| --- | --- |
-| `{ status: "success", preparedOptions, messages? }` | 使用 `preparedOptions` 进入 execution。 |
-| `{ status: "failure", action: "block", reason, messages? }` | owning Check 以 `unavailable` 结算。 |
-| `{ status: "failure", action: "continue", reason, fallback, messages? }` | 使用 `fallback` 进入 execution。 |
+## Definition 与 invocation 的责任
 
-Run 按 Definition 顺序执行所有 Check 的 preflight，完整 barrier 结束后才启动 Check scheduler。preflight throw、malformed result 或 noncanonical prepared value 把 owning Check 结算为 `unavailable`。prepared options 与 fallback 都会成为 detached、deep-frozen 的 invocation-local value；preflight messages 与后续 terminal outcome 共同呈现 preparation 结果。
+### 参数应该放在哪里
 
-Package root 的 `defaultProjectFileSelection` 只是 file-selecting constructor 共用的可组合、深冻结 baseline；spread 该
-value 不会建立跨 Check global config。部分 constructor 原样物化它，具有更窄文件类型能力的 constructor 从相同
-source/exclude 派生精准默认 include；显式 `include` / `exclude` 数组始终由 owning Check 视为完整替换。每项实际默认与
-selected-but-rejected 行为由对应 Check 指南说明。
+**Definition 定义项目怎么检查；Controls 指定这一次怎么运行。** `defineConfig(...)` 的返回值是可重复使用的 Definition，`run(definition, controls?)` 的第二个参数只作用于当前调用；没有本次调整时，使用 `run(definition)`。
 
-## terminal result、Records 与 messages
+| 想设置什么 | 参数位置 | 与另一份输入的关系 |
+| --- | --- | --- |
+| 检查内容、领域 options、依赖与 Check 约束 | Definition 的 `checks` 中各项 Check | Controls 不能替换 Checks 或覆盖 Check options；领域输入继续由 owning Check 或显式 provider 承接。 |
+| Git comparison 与 change-flag regions | Definition 的 `changes` | 每次 Run 在 selection 前获取一次 Git evidence；Controls 不能伪造或直接提供 `vibe-check:change:` flag。 |
+| 调度并行预算、资源总量、策略与终态观察回调 | Definition 的 `scheduler` | Controls 没有 scheduler override，也不能注入 `terminalEffects`。 |
+| 默认 machine、diagnostic 与 progress 输出方式 | Definition 的 `outputs` | 建立可重复使用的默认值；默认目录、预览数量和 formatter 都可在这里配置。 |
+| 本次根目录、选择 flags 与协作取消 | Controls 的 `projectRoot`、`flags`、`signal` | 只属于本次调用，不是 `defineConfig` 字段。 |
+| 本次 Check 产物与 progress 日志目标、diagnostic 文件命名 | Controls 的 `checkArtifactBaseDirectory`、`progressLogFile`、`diagnosticLogFileNaming` | 只属于本次调用；它们本身不是 Definition outputs 的默认值或 override。 |
+| 本次开关输出、更换 machine / diagnostic 目录、调整 progress 预览 | Controls 的 `outputs` | 只覆盖当前调用明确提供的字段，其余继承 Definition 默认值。 |
+| 本次怎样解释有效 Check facts | Controls 的 `checkAggregation` | 可选同步函数；省略时使用严格默认折叠，不改写各项 Check outcome。 |
 
-每个可执行 Check 返回一个 terminal result：`passed` / `failed` 带 Check-owned object final data；`not-applicable` / `unavailable` 以 reason 表示本次调用的数据边界。settlement 会 detach、canonicalize 并关闭 final data；callback throw、malformed result 或 noncanonical data 对应 `unavailable` outcome。
+**两处 `outputs` 是默认值和逐字段覆盖值。** 只关闭本次 machine publication 不影响 progress、diagnostics 或下次调用；省略/`undefined` 不覆盖，`false`、预览数量 `0` 和清除 formatter 的 `null` 有效。字段默认值和示例见[输出指南](guides/run-outputs.md)。
 
-`records.report({ id }, data)` 在 owning Check namespace 内追加 supplemental Record。每个 `id` 非空且在该 Check 内唯一，Record data 使用 canonical JSON object；无效或重复 Record 把 owning Check 结算为 `unavailable`。settlement 保留此前已经接受的 Records。
+相对输出路径从本次 effective `projectRoot` 解析；可复用的默认目录通常放 Definition，本次独占目录通常放 Controls 的对应 output override。Controls 不进入 Definition 的 declarative fingerprint。它也不是任意配置合并对象：unknown fields 会在 author work 前被拒绝；精确 grammar 与结果见下文[RunControls 与 Check aggregation](#runcontrols-与-check-aggregation)。
 
-`messages?` 是 owning Check 可选的有序人读说明；consumer 必须先按 outcome 处理事实，不能用 message presence 推断状态。final data、Records 和 messages 分别承载主要事实、补充事实和人读说明。随包 Check 的额外 message 保证由各自指南说明。
+### 定义与调用如何处理输入
+
+- `defineCheck(value)` 保留 literal `checkId`、options、typed-provider parser 和 `handoff: true` 的 TypeScript inference。它与同 shape 普通 Check object 具有相同 runtime 语义。
+- `defineConfig(value)` 形成带默认 `apiVersion`、outputs 和 scheduler policy 的 Project Definition；可选 `changes` 声明 Git comparison 与 change-flag regions。
+- `defineAdmissionPolicy(value)` 只保留 closed admission policy literal、特别是 custom strategy 的 inference；它与同形 inline policy value 等价。
+- `run(definition, controls?)` 拥有 invocation validation 与 normalization：它关闭递归 Check grammar，detach / canonicalize authored options，并形成 declarative snapshot 与 fingerprint。
 
-## Finding waiver reconciliation
+fingerprint 使用 normalized declarative fields；preparation、execution 与 custom admission callbacks 都保持为执行行为。scheduler fingerprint 区分 `static` 与 `custom`，且不包含 callback identity、source 或 closure。同一份 Definition 可以重复调用，每次 Run 都从 authored input 派生自己的 project context、prepared options、terminal facts 和 output statuses。
 
-`reconcileFindingWaivers({ findings, identify, waivers })` 是 package root 提供的独立 helper，供 custom Check 或其它
-finding producer 在**完整** finding 候选集合形成后对账。`identify(finding)` 对输入顺序中的每个原 finding 接收完整
-finding；调用方自行选择稳定的语义 identity，例如 path、function name 和 metric 的组合。`identify` 的结果与
-`waiver.identity` 都必须可安全 materialize 为 canonical JSON，helper 按 canonical JSON 的结构而非对象引用匹配。
+## 随包 Check 的构造器项目声明
 
-每项 waiver 的 identity 必须唯一且 reason 为非空 string。重复 canonical identity、无法 canonicalize 的 finding 或
-waiver identity、无效 reason，或 malformed / hostile waiver authoring 都抛出 `TypeError`。每个 configured waiver 都在完整
-集合上获得 audit：`0` 次匹配是 `unused`，`1` 次是 `applied`，`>1` 次是 `overmatched`；过宽 waiver 不会豁免任一 finding。
+九个固定身份的随包构造器在现有顶层 options 同时接收领域 policy 与项目 Check 声明：
+`duplicateDetection`、`fileMetrics`、`functionMetrics`、`jsonValidation`、`jsonSchemaValidation`、
+`markdownLinkValidation`、`markdownLint`、`secretDetection` 与 `maintenanceReminders`。前八项使用原有
+object input；`maintenanceReminders(entries)` 保持可用，并增加含 `entries` 的 object input。`commandCheck`
+保持自己的既有 contract。
 
-输出 `findings` 保持输入顺序，并在每项结果中保留同一个原 finding reference。applied waiver 附带的 evidence 是 detached、
-deep-frozen 的 canonical materialization，因此调用方之后修改 authored identity 或 reason 不会改变结果。helper 只返回
-finding disposition 和 waiver audit；它不发布 Record、message 或 terminal outcome。采用它的 Check 自己决定如何发布证据及
-如何结算 actionable finding。
+`PackageCheckAuthoringOptions<Id extends string = string>` 是从 package root 导出的可复用项目声明类型。它的全部字段如下；
+每个字段与 ordinary Check 上的同名字段具有相同含义：
 
-## 递归组合与继承
+| 字段 | 作用 | 详细规则 owner |
+| --- | --- | --- |
+| `checkId?` | 为实例声明 identity；省略时使用该构造器的默认 literal ID。 | Project Definition 的 validation |
+| `displayName?` | 覆盖该构造器的默认显示名。自定义 `checkId` 不会派生新名称。 | 同上 |
+| `enabledByFlags?` | 声明 selection condition。 | [按 flag 选择 Check](guides/extending-check-lifecycle.md#按-flag-选择-check) |
+| `checks?` | 声明 children，使可执行 Check 同时承担 containment scope。 | [递归组合与继承](#递归组合与继承) |
+| `dependsOn?`、`observes?` | 声明 direct relation；可使用 `inherit(...)`。 | [Check 依赖与类型化数据](guides/check-dependencies.md) |
+| `maxParallel?`、`admissionPriority?`、`mutex?`、`resourceClaims?` | 声明 scheduling 与资源需求。 | [调度 Check](guides/scheduling.md) |
+| `omitQuietPassedRow?` | 控制 progress 中 quiet passed row 的呈现。 | [递归组合与继承](#递归组合与继承) |
 
-带 `execution` 的节点形成自己的 outcome；没有 `execution` 的节点只组织子 Check 和 scheduling scope。普通对象字段表示显式 replacement；`inherit({ add, remove })` 只用于在父 `dependsOn` 或 `mutex` collection 上增删。解析后，每个可执行节点拥有自己的 effective options、dependencies、mutexes、visibility 与 parallel budget。
+构造器 input 是 closed top-level object：它只接受所属 Check 的领域字段和这组项目字段。构造器负责安全快照、
+默认 identity/display name、可在本地判断的字段 shape，以及两类字段的分流。默认 overload 返回该 Check 的默认 literal；
+custom overload 要求 input 的静态类型含必填 `{ checkId: Id }`，并返回同一 `Id`；已宽化为通用 options 类型的变量使用
+broad overload，返回 `string` identity。各 Check guide 给出本 Check 的三个签名、默认 identity/display name 与领域字段。
 
-## 类型化依赖数据
+项目字段投影到最终 Check 声明；它们不进入 resolved `.options`、`prepare`、`execute` 或 execution
+`context.options`。随包构造器仍拥有 `prepare`、`execute`、`parseData` 与 handoff 行为，不能通过这些 options 覆盖。
+`defineConfig`/`run` 随后负责完整 tree 的语义校验、normalization 与运行。
 
-producer 同时声明 `execution` 与 `parseData`，从而拥有 final-data contract。consumer 先声明 direct `dependsOn`，再用非泛型 `dependencies.get(checkId)` 读取 canonical data、收窄 `ok`，最后调用 producer 的 parser。
+## 按文件变化选择 Check
 
-### 完整运行示例
+`changes` 让 Definition 从一次 Git comparison 派生选择用的 change flags。`source` 的完整形状是
+`{ compareWith: string }`；`compareWith` 是 Git revision。`flags` 把非空 region ID 映射到 project-root-relative、
+exclude-first glob region。region 的 `include` 必填，`exclude` 可省略且省略等同 `[]`；显式 `undefined`、`null` 或非数组值不合法。
+有效 `projectRoot` 可以嵌套在 repository 内；Git paths 与 region matching 都相对这个 root。
+
+一次 invocation 的数据流固定如下：
+
+```text
+caller flags ─────────────────────────────┐
+Git snapshot → matched change flags ──────┼→ canonical effective flags → selection and project.flags
+Git snapshot ─────────────────────────────└→ project.changes (files or unavailable reason)
+```
+
+可信 snapshot 只发布命中至少一个 region 的稳定 `{ path, flags }` records；一个 path 可命中多个 regions。可信零命中为
+`{ ok: true, files: [] }`，因此不派生 change flag。Git revision、repository 或 path evidence 不可信时为
+`{ ok: false, reason }`，不带 `files`，但会把全部声明的 change flags 加入 effective flags，以保守选择可能依赖它们的 Check。
+Controls 只能传普通 caller flags，不能传入 `vibe-check:change:` prefix。
 
 ```ts
-import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
-
-const CHANGED_FILES_DATA_VERSION = 1 as const;
-
-type ChangedFilesData = Readonly<{
-  readonly files: readonly string[];
-  readonly version: typeof CHANGED_FILES_DATA_VERSION;
-}>;
-
-const changedFiles = defineCheck({
-  checkId: "changed-files",
-  displayName: "Changed files",
-  parseData(data): ChangedFilesData {
-    if (
-      data.version !== CHANGED_FILES_DATA_VERSION ||
-      !Array.isArray(data.files) ||
-      !data.files.every((value): value is string => typeof value === "string")
-    ) {
-      throw new TypeError("Unsupported changed-files data");
+import { changeFlag, defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+const sourceChanged = defineCheck({
+  checkId: "source-changed",
+  displayName: "Source changed",
+  enabledByFlags: { when: changeFlag("source") },
+  execute: ({ project }) => {
+    const changes = project.changes;
+    if (changes === undefined) {
+      return { status: "unavailable", reason: { code: "changes-not-configured" } };
     }
-    return { files: data.files, version: data.version };
-  },
-  execution() {
     return {
       status: "passed",
-      data: { files: ["src/index.ts"], version: CHANGED_FILES_DATA_VERSION }
+      data: {
+        evidence: changes.ok ? "matched" : "unavailable-conservative",
+        effectiveFlags: project.flags,
+        matchedPaths: changes.ok ? changes.files.map(({ path }) => path) : []
+      }
     };
   }
 });
 
-const analyzeChangedFiles = defineCheck({
-  checkId: "analyze-changed-files",
-  displayName: "Analyze changed files",
-  dependsOn: [changedFiles.checkId],
-  execution({ dependencies }) {
-    const read = dependencies.get(changedFiles.checkId);
-    if (!read.ok) return { status: "unavailable", reason: { code: read.error.code } };
-
-    const data = changedFiles.parseData(read.data);
-    return { status: read.status, data: { analyzedFileCount: data.files.length } };
-  }
-});
-
 const definition = defineConfig({
-  checks: [changedFiles, analyzeChangedFiles],
+  changes: {
+    source: { compareWith: "origin/main" },
+    flags: {
+      source: { include: ["src/**"], exclude: ["src/generated/**"] }
+    }
+  },
+  checks: [sourceChanged],
   outputs: {
     diagnosticLogging: { enabled: false },
     machinePublication: { enabled: false },
@@ -146,60 +167,85 @@ const definition = defineConfig({
 
 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 === sourceChanged.checkId)
+  ?.outcome;
+if (outcome?.status !== "passed" && outcome?.status !== "not-applicable") {
+  throw new Error("Change-aware Check did not settle successfully");
+}
 ```
 
-dependency reader 为已声明且具有 `passed` / `failed` final data 的 direct dependency 返回 `ok: true`，并保留 upstream status；其它读取返回包含原因的 `ok: false`。producer parser 负责 shape、invariant 和 compatibility validation，consumer 显式调用它恢复 provider data。七个随包 Check 都提供 `parseData` 和同实现的 package-root parser；名称与类型见各自指南。
+这个示例的 Check 由 `changeFlag("source")` 选择：命中时读取可信 paths，可信零命中时结算为
+`not-applicable`，unavailable evidence 时仍运行但以 `changes.ok === false` 区分结果。`project.flags` 始终是上图的 canonical effective set；`project.changes` 才是 files 或 unavailable reason 的
+evidence channel。要编写 condition、`prepare` 或 `execute`，继续阅读[Check lifecycle](guides/extending-check-lifecycle.md)。
 
-## RunControls 与 Check aggregation
+## options preparation 与 execution
 
-`RunControls` 只作用于一次 `run(definition, controls)`：
+Check 在获准入后执行自己的 `prepare(options, signal, project?)`，再以 prepared options 或 fallback 进入 `execute`；block 或非法准备结果使本项 `unavailable`。不同 prepared shape 的类型要求、三种返回形式、冻结与取消边界见[自定义 Check 的 `prepare`](guides/extending-check-lifecycle.md#prepare准备阻止或带-fallback-继续)。
+
+## terminal result、Records 与 messages
+
+每个可执行 Check 返回一个 terminal result：`passed` / `failed` 带 Check-owned object final data；`not-applicable` 表示本次无适用工作，可省略 reason；`unavailable` 表示无法形成可信结论，必须带非空 `reason.code`。两者都没有 final data；无领域 data 的成功/失败结果可返回 `{}`。settlement 会 detach、canonicalize 并关闭 final data；callback throw、malformed result 或 noncanonical data 对应 `unavailable` outcome。
+
+需要在同一 Run 的 direct prerequisite 间保留引用 identity 时，provider 在 `defineCheck({ handoff: true, ... })` 作最小声明，并只在 accepted `passed` result 返回 non-null object/function reference。handoff 类型由该 result 自动推断；direct `dependsOn` consumer 以 `dependencies.get(provider)` 一次取得 canonical data 和 typed reference。provider 的 `parseData` 仍只处理 canonical data。`handoff: true` 背后的 WeakMap identity 是 Product 内部细节；handoff 是 invocation-private capability，不属于 terminal Check facts。
 
-- `projectRoot` 决定项目相对路径的解析根。
-- `flags` 成为 callback 可读的 normalized project context。
-- `signal` 供 preflight 与 execution 协作取消；取消结果记录对应 phase。
-- `outputs` 覆盖本次 diagnostic logging、machine publication 或 progress rendering。
-- `checkAggregation` 选择 `checks`，并以 `all` / `any`、`unavailable`、`notApplicable` 与 `empty` policy 形成 invocation aggregate。
+final data 与 Record data 使用 canonical JSON object：root 不能是数组，拒绝不支持的 prototype/descriptor、getter、cycles、sparse arrays 和 non-finite numbers，不调用 `toJSON`。接受后形成 detached、deep-frozen 的 null-prototype facts；不要依赖 JavaScript own-key enumeration 推断 canonical 文本顺序。
 
-aggregation 是 terminal outcomes 之外的 invocation-level fact。它在完整 terminal facts 结算后产生 `passed`、`failed`、`not-applicable` 或 `unavailable`；未配置 policy 时 `aggregate` 为 `null`。consumer 需要调用级结论时显式选择 policy，同时保留每项 Check outcome。
+`records.report({ id }, data)` 在 owning Check namespace 内追加 supplemental Record。每个 `id` 非空且在该 Check 内唯一，Record data 使用 canonical JSON object；无效或重复 Record 把 owning Check 结算为 `unavailable`。settlement 保留此前已经接受的 Records；Record 数量不决定 status。结算后 reporter 关闭，late write 抛错且不能更改事实。
 
-Check-specific invocation facts 由 owning Check 的 options 或 producing Check 的 final data 承载。多个 Checks 共享同一事实时，producer 负责 acquisition policy 与 data shape，下游通过 direct `dependsOn` 读取；上面的 typed dependency 示例聚焦这条 data handoff。
+`messages?` 是 owning Check 可选的有序人读说明；consumer 必须先按 outcome 处理事实，不能用 message presence 推断状态。final data、Records 和 messages 分别承载主要事实、补充事实和人读说明。随包 Check 的额外 message 保证由各自指南说明。
+
+author `messages` 是无空洞的有序数组，每项是精确 `{ level, code, message }`：level 为 `info | warning | error`，code 和 message 均为非空字符串。Product 不 trim、Unicode normalize、去重或设置 item/正文长度上限；省略、自有 `undefined` 和 `[]` 都表示无 messages。非法 attachment 使 owning Check 不可用且不接受 partial messages。捕获的 console 复用同一 readback shape，使用 `console-<method>` code。
+
+progress 只呈现这些事实，不修改它们。预览默认值、formatter、console capture 与日志见[配置 Run 输出与诊断](guides/run-outputs.md)。
 
-## outputs 与 RunResult 边界
+## 递归组合与继承
+
+每个节点使用唯一 `checkId` 和非空 `displayName`；可执行节点也可以包含子节点，containment 只贡献 scheduling scope，不额外产生 snapshot 层级。带 `execute` 的节点形成自己的 outcome；没有 `execute` 的节点只组织子 Check 和 scheduling scope。普通对象字段表示显式 replacement；`inherit({ add, remove })` 只用于在父 `dependsOn`、`observes` 或 `mutex` collection 上增删。解析后，每个可执行节点拥有自己的 effective options、passed prerequisites、terminal observations、mutexes、normalized `omitQuietPassedRow` 人读呈现策略、parallel budget 与 admission priority。该策略不继承给 children，也不属于 terminal facts；它只供 progress renderer 决定 quiet-pass row 的保留与编号格式。
 
-Definition outputs 提供 diagnostic logging、machine publication 与 progress rendering 三项独立 defaults，RunControls 可以只覆盖当前调用需要的部分。configuration 成功后的职责如下：
+## 类型化依赖数据
 
-- 只有 diagnostic logging 或 machine publication 至少一项启用时，Run 才在创建 invocation 阶段捕获一次 immutable wall-clock `startedAtUtc`；两项都禁用时不读取或序列化 wall clock。
-- 启用的 diagnostic logging 在 preflight 前以该 instant 命名 UTC-compact log path，并按事实形成顺序记录 Product core 已知的 invocation、planning、scheduler、handoff 与 output 时间线。每个事件以序号、单调 elapsed、可筛选的 `[]` 标签和 event name 开始；普通事实使用 `key=value`，超出当前主行容量的事实进入有界 continuation line。标签只突出 Run、Check、phase、Scheduler decision 和 outcome 等高频阅读轴；Scheduler decision 的顶层 `kind` / `taskId` 与 Record observation 的顶层 `result` 已由标签完整表达时，不在 facts 中重复。
-- 启用的 machine publication 将同一个 instant 投影为 `run.json` 的 `invocation.timestamp`，所以 timestamp 不是 publication 完成时间；两项同时启用时，日志文件名与 machine timestamp 必须共享该一次捕获。
-- progress rendering 呈现人读 lifecycle。三项 output 都由 Run 调度，并分别返回 status。
+使用 direct `dependsOn` 取得成功 prerequisite，使用 direct `observes` 等待并审计任意终态；从 string `dependencies.get` / `list` 读取冻结事实，再由 producing Check 的 `parseData` 恢复业务类型。以 `handoff: true` 声明的 provider object 可用于 `dependencies.get(provider)`，向 direct prerequisite consumer 同时交付 frozen canonical data 与 same-Run reference。完整的[依赖数据指南](guides/check-dependencies.md)说明读取授权、继承、parser、identity 与 cleanup 边界，并给出运行示例。
 
-这些 diagnostic 行不建立可解析 schema。Run 结束前最后一条可写 diagnostic event 是 `run.terminal-before-log-close`：它只证明 terminal fact 已写入、logger close 尚未确认，随后才尝试关闭日志。
+## RunControls 与 Check aggregation
+
+`RunControls` 只作用于一次 `run(definition, controls)`：
+
+- `projectRoot` 决定项目相对路径的解析根；省略时使用调用时的工作目录。
+- `flags` 是可省略的 dense 非空 string-token 数组，省略、`undefined` 或 `[]` 得到冻结空数组；合法 tokens 被复制、去重并稳定排序，完整集合进入 callback project context。
+- `checkArtifactBaseDirectory` 是可选、invocation-only 的 Check artifact base；它使用非空且无 U+0000 的受信任 directory grammar，relative text 从 effective `projectRoot` 解析，absolute text 直接作为 target。它不进入 Definition fingerprint，不创建 output status，也不授予 Check 读取 base、sibling directory、machine/diagnostic output 或 cross-Run state 的能力；没有配置时 callback 的 `artifactDirectory` 为 `null`。
+- `progressLogFile` 是可选、invocation-only 的 terminal-progress tee target，使用同一非空且无 U+0000 target grammar；它不会改变 Definition outputs、Definition fingerprint 或 Check callback capability。
+- `signal` 供 preparation 与 execution 协作取消；取消结果记录对应 phase。
+- `diagnosticLogFileNaming` 可选 `"unique"`（默认）或 `"channel"`，只控制本次 core/scheduler 日志 basename，不启用 diagnostics、不进入 Definition fingerprint。
+- `checkAggregation` 可选为同步 `CheckAggregation` 函数：`(checks: readonly CoreCheck[]) => CheckAggregate`。Product 只在完整结算后按 canonical Check order 传入本次有效列表；它不传入未选 Check、完整 snapshot、Records、messages、输出状态或控制对象。`CoreCheck` 提供 `checkId`、四态 `outcome`，以及 passed/failed outcome 的既有 final data。
+
+aggregation 是 terminal outcomes 之外的 invocation-level fact。省略函数时，非空有效列表且所有 Check 都为 `passed` 得到 `passed`；空列表或任一 `failed`、`unavailable`、`not-applicable` 得到 `failed`。提供函数时，它可以同步返回闭合四态 `passed`、`failed`、`not-applicable` 或 `unavailable`，以调用方的领域规则解释同一列表。函数不能等待、选择 Check、修改 facts 或进入 Definition fingerprint。
+
+例如，下面的调用方只把有效列表中的 `failed` 视为本次领域失败；函数直接返回字面量，不能标记为 `async`：
+
+```ts
+const result = await run(definition, {
+  checkAggregation(checks) {
+    return checks.some((check) => check.outcome.status === "failed") ? "failed" : "passed";
+  }
+});
+```
 
-只有 non-configuration `RunResult` 具有有效 output configuration 与 `outputs` readback。此时
-`outputs.diagnosticLogging` 的形状为 `{ enabled, status, file }`，其中 `status` 是
-`"disabled" | "not-run" | "succeeded" | "failed"`；禁用时 `file` 为 `null`，启用时即使文件创建失败也保留预先计算的、
-project-root-relative `run-<UTC 紧凑时间>-<UUID>.log` 目标。无效 Definition、controls 或 aggregation selection 直接返回
-configuration diagnostic，不创建诊断日志。
+函数抛错、抛出非 `Error` 值、返回 Promise/thenable 或其它值会使 `run(...)` 的 Promise 直接拒绝；这不是 `RunResult` 的 configuration、execution 或 output branch。Product 关闭本次 diagnostic/progress writer，不呈现正常成功 summary，也不发布正常 machine result。调用方应在 `await run(...)` 周围按自己的错误边界处理这类 authoring fault；普通 Definition、Controls、planning、Check execution 和 output 故障仍按既有 `RunResult` 分支结算。
 
-diagnostic logging 只服务当前人工诊断：它没有 parser、schema/version、跨版本格式兼容、`latest`、retention 或跨 invocation
-discovery contract，也不替代 Check final data、Record、terminal message 或 Check/process adapter 自有的 transcript。logging
-failure 只把该 output 标为 failed，不改写已形成的 Check/Record facts，也不阻断 progress rendering 或 machine publication 的
-闭合。多个 output 都失败时，`RunResult.outputs` 保留每项 status；唯一 `output` diagnostic 依次选择 progress rendering、
-machine publication、diagnostic logging。diagnostic logging 不进入 machine v4；其 machine-field 排除见
-[机器输出契约](output.md)。Check final-data parser 只处理已经取得的单个 data object，不替代该契约。
+## RunResult 分支
 
-progress rendering 在 TTY 中维护 running region，在 plain output 与 `TERM=dumb` 中只追加 settled rows。`visibility: "attention"` 只隐藏无 messages 的 passed settled row，不改变 outcome、Records 或 machine output；accepted message 的 code 保留在 `RunResult.checkMessages`，终端只呈现 level 与正文。renderer failure 进入对应 output status，不改写已形成的 Check facts。
+输出的配置、日志目标、readback statuses 和 failure 优先级见[配置 Run 输出与诊断](guides/run-outputs.md#输出状态与失败处理)。本节说明调用方如何先判别 Run，再读取 Check facts。
 
 按 `RunResult.kind` 和 cancellation phase 读取结果：
 
 | 分支 | 可用 facts 与处理方式 |
 | --- | --- |
-| `completed` | 完整 `snapshot`、`checkDurations`、`checkMessages`、`outputs` 与可选 `aggregate`；继续读取单项 Check outcome。 |
-| `output` | 完整 Check facts 与 output failure diagnostic；消费 facts 并处理失败的 output。 |
-| `cancelled` / `phase: "execution"` | 取消时关闭的 snapshot、durations 与 messages；按 cancellation result 处理。 |
+| `completed` | 完整 `snapshot`、`checkDurations`、`checkMessages`、`outputs` 与非空四态 `aggregate`；继续读取单项 Check outcome。handoff 已在 execution graph 关闭时清除，不在此结果中。 |
+| `output` | 完整 `snapshot`、`checkDurations`、`checkMessages` 与四态 `aggregate`，另有 output failure diagnostic；消费 facts 并处理失败的 output。 |
+| `cancelled` / `phase: "execution"` | 取消时关闭的 snapshot、durations 与 messages；没有 aggregate，按 cancellation result 处理。 |
 | `cancelled` / `phase: "pre-work"` 或 `"planning"` | invocation metadata 与 cancellation phase；按 phase 结束调用。 |
-| `configuration` | Definition、controls 或 aggregation selection diagnostic；project callback 执行数为零。 |
+| `configuration` | Definition 或 Controls diagnostic；project callback 执行数为零。 |
 | `planning` | task-graph diagnostic 与 invocation metadata。 |
-| `execution` | Product execution-settlement diagnostic 与 invocation metadata。 |
+| `execution` | Product execution-settlement diagnostic 与 invocation metadata。`diagnostic.code === "admission-policy-failed"` 表示 custom policy 已停止 admission、取消 pending 并 drain started work；它不是 Check terminal status，也不携带 partial snapshot。 |
 
-Check `failed` 是已结算的业务 outcome；Run `execution` 是 invocation infrastructure diagnostic；Run `output` 是完整 Check facts 附带的 diagnostic logging、publication 或 rendering failure diagnostic。
+Check `failed` 是已结算的业务 outcome；Run `execution` 是 invocation infrastructure diagnostic；Run `output` 是完整 Check facts 附带的 output failure diagnostic。