@zxyycom/vibe-check 0.0.1 → 0.0.3

package/docs/checks/json-schema-validation.md

@@ -1,12 +1,60 @@
 # `jsonSchemaValidation`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页说明 `jsonSchemaValidation` 的 options、terminal effects 与安全边界。该 Check 使用显式 schema registry 与
-instance bindings 验证选定的 JSON instances。`jsonSchemaValidation(options?)` 补齐默认值并返回可直接放入 Project
-Definition `checks` 的普通 Check。
+`jsonSchemaValidation(options?)` 构造普通 Check，使用显式 schema registry 与 instance bindings 验证 JSON instances。
+先声明 schema 与 binding；无参调用不发现 schema，并结算为 `not-applicable / no-bindings`。
+
+## 构造器项目声明
+
+`jsonSchemaValidation` 有三类 overload：
+`jsonSchemaValidation(options?: JsonSchemaValidationOptions<"json-schema-validation">)` 保留默认 literal；
+`jsonSchemaValidation<Id>(options: JsonSchemaValidationOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `JsonSchemaValidationOptions` 的变量返回 `string` identity。默认 `checkId` 是 `json-schema-validation`，默认 `displayName` 是 `JSON Schema validation`；`files`、
+`maximumBytes`、`schemaIdentity`、`referenceResolution`、`schemas` 与 `bindings` 仍是本 Check 的领域 options。
+
+例如，将 API schema 校验声明为只在 API 变更时选择的独立 Check：
+
+```ts
+const apiSchema = jsonSchemaValidation({
+  checkId: "api-schema",
+  enabledByFlags: { when: "api-changed" },
+  schemas: [{ id: "urn:example:api", path: "schema/api.json" }],
+  bindings: [{ id: "api", instancePath: "fixtures/api.json", schemaId: "urn:example:api" }]
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, jsonSchemaValidation, run } from "@zxyycom/vibe-check";
+
+const configured = {
+  schemas: [{ id: "urn:example:config", path: "schema/config.json" }],
+  bindings: [
+    { id: "config", instancePath: "config.json", schemaId: "urn:example:config" }
+  ]
+};
+const schemaCheck = jsonSchemaValidation(configured);
+const result = await run(defineConfig({
+  checks: [schemaCheck],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === schemaCheck.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`JSON Schema validation did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -21,17 +69,11 @@ Definition `checks` 的普通 Check。
 }
 ```
 
-上面的代码块是无参调用物化后的完整 resolved options；`defaultProjectFileSelection` 是 package root 公开的同值深冻结
-基线；完整默认 glob 可直接从该 public value 读取。六个顶层 authoring fields 都可省略；`files` 内的三个字段也可分别省略。显式 `schemas`、`bindings` 与
-`referenceResolution.sources` 数组是完整替换值。`schemaIdentity` 与
-`referenceResolution` 的显式 discriminated branch 必须自身完整。无参调用不会发现 schema；由于 `bindings: []`，它结算为
-`not-applicable / no-bindings`。constructor 返回后若通过普通对象组合替换 `check.options`，replacement 才必须保留完整
-resolved shape。
-
-- `files` 完整定义本 Check 可读取的 local paths；source 可选 `filesystem` 或 `git-worktree`，selected path 必须命中
-  `include` 且不能命中 `exclude`。filesystem 不解释 `.gitignore`；git-worktree 使用已跟踪文件和未被 Git 标准忽略
-  规则排除的未跟踪文件。schema 与 instance 的读取 scope 是 selected set；来源不可用时 Check 结算为
-  `unavailable`，不会切换到另一来源。
+无参调用物化上述完整 options；`files` 使用 package root 公开的深冻结 `defaultProjectFileSelection` 基线。
+六个顶层字段及 `files` 子字段都可省略；显式 `schemas`、`bindings`、`referenceResolution.sources` 数组完整替换默认值。
+`schemaIdentity` 与 `referenceResolution` 的显式 discriminated branch 必须完整；constructor 后替换 `check.options` 也须保留完整 resolved shape。
+
+- `files` 遵循[共享 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)，selected set 是 schema 与 instance 的本地读取 scope；来源不可用时不切换来源。
 - `maximumBytes` 是每个 schema 或 instance document 的 raw byte 上限，必须是正安全整数。
 - `schemas` 每项为 `{ id, path }`；schema `id` 是 1–256 字符且没有 credentials、query 或 fragment 的绝对
   `https:` / `urn:` identity，`path` 是 1–512 字符的 normalized project-relative 小写 `.json` path。schema ID 与 path
@@ -82,11 +124,12 @@ fragment 的精确 HTTPS origin；`pathPrefix` 最长 256 字符，从 `/` 开
 
 ## 工作原理
 
-constructor 先关闭 authoring shape、补齐并冻结 resolved options。Run 的全局 preflight barrier 验证完整 options 后，zero
-bindings 结算为 `not-applicable`；其它调用从 `files`
-selection 建立可读 path set，加载 registered schemas，按 identity policy 编译，再验证每个 binding。selected set
-之外的声明 path 形成 `out-of-scope` domain issue，读取 scope 保持为 selected set。schema document、compile 与
-instance issues 形成 Records。
+constructor 补齐并冻结 closed options；获 Scheduler admission 后先 preparation，再建立 selected path set、加载 registry、
+按 identity policy 编译并验证 bindings。selected set 外的声明路径形成 `out-of-scope` issue，不扩大读取范围。
+schema document、compile 与 instance issues 均形成 Records。
+
+local schema 与 instance document 复用 [JSON Validation 工作原理](json-validation.md#工作原理)定义的 strict-document
+boundary；本指南只增加 schema identity、reference resolution、binding 与 engine settlement，不建立另一套 JSON 解析规则。
 
 ## 效果与结果
 
@@ -159,7 +202,7 @@ binding 数量为零时结算为 `not-applicable / no-bindings`。`unavailable.r
 
 任一 `unavailable` 分支都不提供 final data；此前已经接受的 issue Records 继续保留。
 
-通用 preflight 语法见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+通用 preparation 语法见 [options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 
@@ -167,21 +210,6 @@ binding 数量为零时结算为 `not-applicable / no-bindings`。`unavailable.r
 remote scope；每次 response 最多读取 1,048,576 bytes，单次请求 timeout 为 5 秒。request 不携带 credentials 或 custom
 headers，也不跟随 redirect。remote reference authorization 保持 local file selection 不变。
 
-## 最小用法
-
-```ts
-import { defineConfig, jsonSchemaValidation, run } from "@zxyycom/vibe-check";
-
-const configured = {
-  schemas: [{ id: "urn:example:config", path: "schema/config.json" }],
-  bindings: [
-    { id: "config", instancePath: "config.json", schemaId: "urn:example:config" }
-  ]
-};
-const schemaCheck = jsonSchemaValidation(configured);
-const result = await run(defineConfig({ checks: [schemaCheck] }));
-```
-
 ## 适用边界
 
 该 Check 适用于显式 schema registry 与 bindings。JSON Schema `format` 使用 2020-12 annotation 语义，不加载 format

package/docs/checks/json-validation.md

@@ -1,12 +1,52 @@
 # `jsonValidation`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页说明 `jsonValidation` 的 options、terminal effects 与安全边界。该 Check 严格验证自己选择且以小写
-`.json` 结尾的文档，并报告 syntax error、duplicate key 与 incomplete document。`jsonValidation(options?)` 补齐默认值并
-返回可直接放入 Project Definition `checks` 的普通 Check。
+`jsonValidation(options?)` 构造普通 Check，严格验证所选小写 `.json` 文档的完整性，报告 syntax error、duplicate key
+与 incomplete document。
+
+## 构造器项目声明
+
+`jsonValidation` 有三类 overload：`jsonValidation(options?: JsonValidationOptions<"json-validation">)`
+保留默认 literal；`jsonValidation<Id>(options: JsonValidationOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `JsonValidationOptions` 的变量返回 `string` identity。默认 `checkId` 是 `json-validation`，默认 `displayName` 是 `JSON validation`；`files` 与
+`maximumBytes` 仍是本 Check 的领域 options。
+
+例如，用明确的项目 identity 和展示名只检查配置文件：
+
+```ts
+const configJson = jsonValidation({
+  checkId: "config-json",
+  displayName: "Configuration JSON",
+  files: { include: ["config/**/*.json"] }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, jsonValidation, run } from "@zxyycom/vibe-check";
+
+const check = jsonValidation();
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`JSON validation did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -21,16 +61,12 @@
 }
 ```
 
-上面的代码块是无参调用物化后的完整 resolved options；`exclude` 表示 constructor detached-copy 了 package root 公开
-`defaultProjectFileSelection.exclude` 的全部条目，不是调用方必须复制的输入。authoring options 的 `files` 与
-`maximumBytes` 都可以省略；`files.source`、`files.include` 与 `files.exclude` 也可分别省略。source 可选 `filesystem` 或
-`git-worktree`，selected path 必须命中
-`include` 且不能命中 `exclude`。只有其中 case-sensitive `path.endsWith(".json")` 的 paths 成为输入。
-filesystem 不解释 `.gitignore`；git-worktree 使用已跟踪文件和未被 Git 标准忽略规则排除的未跟踪文件。两种来源都使用
-本页 `files` branch 的 `include` / `exclude` glob；来源不可用时 Check 结算为 `unavailable`，不会切换到另一来源。
-`maximumBytes` 是每个 raw JSON document 的 byte 上限，必须是正安全整数。显式 `include` / `exclude` 数组是完整替换值；
-例如显式 `include: ["**/*"]` 会选择其它类型，Check 将为每个不受支持的 path 发布拒绝 Finding，而不会静默过滤。
-constructor 返回后若通过普通对象组合替换 `check.options`，该 replacement 才必须提供完整 resolved shape。
+无参调用物化上述完整 options，其中 `exclude` 是公开 `defaultProjectFileSelection.exclude` 的独立副本。
+`files`、其子字段和 `maximumBytes` 都可省略；`maximumBytes` 必须是正安全整数。
+
+文件来源、glob 与数组替换遵循[共享 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)。
+本 Check 只读取 case-sensitive `path.endsWith(".json")` 的 selected paths；宽泛 include 选中的其它路径发布拒绝 Finding，
+不静默过滤。constructor 后替换 `check.options` 时，必须提供完整 resolved shape。
 
 ### 定制 authoring options
 
@@ -46,9 +82,12 @@ const configJsonValidation = jsonValidation({
 
 ## 工作原理
 
-constructor 先关闭 authoring shape、补齐并冻结 resolved options。Run 的全局 preflight barrier 再验证该完整 options；
-execution 收集 selected paths，按小写 `.json` suffix 完整分成 accepted/rejected。每个 rejected path 先产生 supplemental
-Record，accepted path 才通过 strict-document boundary 读取和解析；无效文档产生另一种 supplemental Record。
+constructor 补齐并冻结 closed options，获 Scheduler admission 后先 preparation，再按本页 suffix 规则完整分类输入。
+每个 rejected path 先发布 Record；accepted path 才读取、解析，无效文档另发 Record。
+
+strict-document boundary 先按 byte length 应用 `maximumBytes`，再依次区分 BOM、fatal UTF-8、strict JSON grammar 与 decoded
+duplicate key；每个文档只返回最先成立的封闭 reason。合法文档只向 owning Check 交付不含 prototype 的深冻结私有值，
+不会保留 source、AST、key 或 parser detail；读取或边界执行失败结算为 unavailable，而不是伪装成 invalid document。
 
 ## 效果与结果
 
@@ -112,21 +151,14 @@ Records 与 warning 的 `passed` 结算。`unavailable.reason.code` 只使用以
 | `execution-cancelled` | invocation signal 在可观察工作边界取消本 Check | 检查调用方取消原因，不把结果解释为 clean validation |
 
 后续文件导致 `unavailable` 时，分类阶段的 rejected-input Records 与先前已接受的 invalid-file Records 均保留，但本 Check
-不提供 final data；对应 rejection warning 也随 terminal error message 一起保留。通用 preflight 语法见
-[options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+不提供 final data；对应 rejection warning 也随 terminal error message 一起保留。通用 preparation 语法见
+[options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 
 I/O scope 是 `files` 选中且通过小写 `.json` eligibility 的本地文件；rejected path 只形成事实，不读取内容。external
 command 和 network request 数均为零。
 
-## 最小用法
-
-```ts
-import { defineConfig, jsonValidation, run } from "@zxyycom/vibe-check";
-const result = await run(defineConfig({ checks: [jsonValidation()] }));
-```
-
 ## 适用边界
 
 该 Check 适用于 JSON document integrity；需要按 schema 评估字段与结构时使用

package/docs/checks/maintenance-reminders.md

@@ -1,11 +1,67 @@
 # `maintenanceReminders`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页说明 `maintenanceReminders` 的输入、terminal effects 与安全边界。`maintenanceReminders(entries)` 创建一个固定
-ID 为 `maintenance-reminders` 的 Check，用 Git first-parent history 提醒定期复核维护事项。
+`maintenanceReminders(entries)` 创建固定 ID 为 `maintenance-reminders` 的 Check，用 Git first-parent history 提醒定期复核。
+
+## 构造器项目声明
+
+`maintenanceReminders` 保留 `maintenanceReminders(entries)`，并为 object input 提供三类 overload：
+`MaintenanceRemindersInput<"maintenance-reminders">` 保留默认 literal；带必填
+`{ checkId: Id }` 的 `MaintenanceRemindersInput<Id>` 保留 custom literal；宽化为
+`MaintenanceRemindersInput` 的变量返回 `string` identity。默认 `checkId` 是 `maintenance-reminders`，默认
+`displayName` 是 `Maintenance reminders`；`entries` 是唯一领域 policy，object input 的其余顶层字段用于项目声明。
+
+例如，为需要单独选择的提醒设置 identity 与 flag 条件：
+
+```ts
+const dependencyReview = maintenanceReminders({
+  checkId: "dependency-review",
+  enabledByFlags: { when: "dependencies-changed" },
+  entries: [{
+    id: "dependencies",
+    baseCommit: "0123456789abcdef0123456789abcdef01234567",
+    limits: { commits: 40 },
+    message: "Review dependency updates."
+  }]
+});
+```
+
+两种调用形式都返回原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, maintenanceReminders, run } from "@zxyycom/vibe-check";
+const check = maintenanceReminders([
+  {
+    id: "docs",
+    baseCommit: "0123456789abcdef0123456789abcdef01234567",
+    limits: { commits: 40 },
+    message: "Review docs.",
+    mode: "enforcing"
+  }
+]);
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`Maintenance reminders did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+将占位 commit ID 换成项目 first-parent history 中的真实复核 commit；不存在的基线产生条目 `unavailable`。
+示例使用 `enforcing`，会因到期或不可测量失败；默认 `advisory` 只提醒。
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -30,8 +86,8 @@ ReadonlyArray<{
 - `message` 是到期或不可测量时展示的非空人读正文。
 - `mode` 省略时为 `advisory`；`enforcing` 使到期或不可测量的条目令所属 Check 失败。
 
-constructor 把输入固定为完整 options `{ entries, git: { executable: "git" } }`。所属 Check 的 preflight 在任何 Check
-execution 开始前验证 unknown、sparse、duplicate 或 malformed entries；失败时当前 Check 以
+constructor 把输入固定为完整 options `{ entries, git: { executable: "git" } }`。所属 Check 获 Scheduler admission 后，其 task-local
+preparation 在自身 execution 前验证 unknown、sparse、duplicate 或 malformed entries；失败时当前 Check 以
 `unavailable / invalid-options` 结算。
 
 ## 工作原理
@@ -87,12 +143,11 @@ type FinalData = Readonly<{ entries: readonly EntryAssessment[] }>;
 | `unavailable` | 附加 warning，不贡献失败。 | 附加 error，并令所属 Check 失败。 |
 
 `due` message code 是 `maintenance-reminder-due`，`unavailable` message code 是
-`maintenance-reminder-unavailable`。任一 `enforcing` entry 为 `due` 或 `unavailable` 时 Check outcome 为 `failed`；否则为
-`passed`。`due` message 正文是 `<id>: <message>`；`unavailable` 还在末尾追加 ` (<reason>)`。该 Check 不发布
-supplemental Records；条目也不会成为独立 Check、aggregation target 或 progress row。
+`maintenance-reminder-unavailable`。有条目贡献失败则 Check 为 `failed`，否则为 `passed`。
+`due` 正文是 `<id>: <message>`；`unavailable` 追加 ` (<reason>)`。不发布 supplemental Records；条目不成为独立
+Check、aggregation target、progress row 或 machine row。
 
-启用 machine publication 时，entries 只作为一项普通 `maintenance-reminders` Check 的 final data；entry 不形成独立
-machine row，terminal messages 也不进入 machine files。
+启用 machine publication 时只发布所属 Check 的 final data，terminal messages 不进入 machine files。
 
 用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseMaintenanceRemindersData(value)` 验证 final data。parser
 验证每个 discriminated assessment、commit ID、唯一 reminder ID、计数、`exceeded` 与 reason 不变量，并返回
@@ -127,32 +182,13 @@ Git/历史测量的普通失败会保留完整 final data，并把受影响条
 每个 whole-Check `unavailable` 都携带与 `reason.code` 相同 code 的 error message，并指出应恢复 options、检查取消原因或
 检查 package/runtime integrity。entry-level `unavailable` 仍按上一节保留 final data 与项目编写的提醒正文。
 
-通用 preflight 语法见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+通用 preparation 语法见 [options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 
 I/O boundary 是本机 Git 对 committed first-parent history 的 read-only 查询。workspace、staging area 与 network
 request 数为零，baseline 更新由维护者提交。
 
-## 最小用法
-
-```ts
-import { defineConfig, maintenanceReminders, run } from "@zxyycom/vibe-check";
-const check = maintenanceReminders([
-  {
-    id: "docs",
-    baseCommit: "0123456789abcdef0123456789abcdef01234567",
-    limits: { commits: 40 },
-    message: "Review docs."
-  }
-]);
-const result = await run(defineConfig({ checks: [check] }));
-```
-
-示例 commit ID 只是 shape 占位值，必须替换为当前项目 first-parent history 中的真实复核 commit。若直接使用不存在的
-占位值，条目会得到 `assessment: "unavailable"`；这不是一次成功的维护基线配置。
-
 ## 适用边界
 
-该 Check 适用于按 commit count 或 changed-line count 提醒维护复核。是否把 `enforcing` failure 转为调用级阻断，
-由 `RunControls.checkAggregation` policy 决定。
+该 Check 适用于按 commit count 或 changed-line count 提醒维护复核。有效的 `enforcing` failure 会使默认严格 `aggregate` 为 `failed`；调用方负责把该调用级结论映射为自己的阻断或退出行为。只有需要不同领域解释时，才提供 `RunControls.checkAggregation` 同步函数。

package/docs/checks/markdown-link-validation.md

@@ -1,12 +1,54 @@
 # `markdownLinkValidation`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页说明 `markdownLinkValidation` 的 options、terminal effects 与安全边界。该 Check 离线验证 selected Markdown
-sources 中的本机链接、图片目标与标题锚点。`markdownLinkValidation(options?)` 补齐默认值并返回可直接放入 Project
-Definition `checks` 的普通 Check。
+`markdownLinkValidation(options?)` 构造普通 Check，离线验证所选 Markdown 中的本机链接、图片目标与标题锚点。
+
+## 构造器项目声明
+
+`markdownLinkValidation` 有三类 overload：
+`markdownLinkValidation(options?: MarkdownLinkValidationOptions<"markdown-link-validation">)` 保留默认 literal；
+`markdownLinkValidation<Id>(options: MarkdownLinkValidationOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `MarkdownLinkValidationOptions` 的变量返回 `string` identity。默认 `checkId` 是 `markdown-link-validation`，默认 `displayName` 是 `Markdown link validation`；`files`、
+`findingPolicy`、target policy、`cache` 与 `limits` 仍是本 Check 的领域 options。
+
+例如，让文档链接检查观察生成文档并使用独立 identity：
+
+```ts
+const docsLinks = markdownLinkValidation({
+  checkId: "documentation-links",
+  observes: ["generate-docs"],
+  files: { include: ["docs/**/*.md"] }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
+
+const check = markdownLinkValidation({ findingPolicy: "blocking" });
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`Markdown link validation did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+示例显式使用 `findingPolicy: "blocking"`，让普通链接 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -23,6 +65,9 @@ Definition `checks` 的普通 Check。
   validateCrossDocumentAnchors: true,
   rootExternalTargetMode: "report",
   requireNonEmptyDirectories: false,
+  cache: {
+    enabled: false
+  },
   limits: {
     maxMarkdownBytes: 1_048_576,
     maxOccurrences: 10_000,
@@ -31,23 +76,19 @@ Definition `checks` 的普通 Check。
 }
 ```
 
-上面的代码块是无参调用物化后的完整 resolved options；`exclude` 表示 constructor detached-copy 了 package root 公开
-`defaultProjectFileSelection.exclude` 的全部条目，不是调用方必须复制的输入。所有顶层 authoring fields 都可省略，
-`files` 与 `limits` 内的字段也可分别省略。显式 `include` / `exclude` 数组是完整替换值；显式宽泛 include 选中的非 Markdown
-path 会产生拒绝 Finding，而不是被静默过滤。
-
-- `files` 定义 Markdown source selection；source 可选 `filesystem` 或 `git-worktree`，selected path 必须命中
-  `include` 且不能命中 `exclude`。filesystem 不解释 `.gitignore`；git-worktree 使用已跟踪文件和未被 Git 标准忽略
-  规则排除的未跟踪文件。其中 extension 大小写不敏感的 `.md` / `.markdown` 成为 sources，direct targets 仅用于
-  resolution；来源不可用时 Check 结算为 `unavailable`，不会切换到另一来源。
-- `findingPolicy` 为 `blocking | non-blocking`，默认 `non-blocking`。它只结算本 Check 的 normal local-reference
-  findings：`blocking` 使 finding outcome 为 `failed`，`non-blocking` 保留相同的 Records、计数与 final data，但以
-  `passed` outcome 和 warning message 提示；它不会改写 Project Run、aggregation 或 Gate outcome。
+无参调用物化上述完整 options，`exclude` 是公开 `defaultProjectFileSelection.exclude` 的独立副本。
+所有顶层字段及 `files`、`limits` 子字段都可省略。
+
+- `files` 遵循[共享 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)。只有大小写不敏感的
+  `.md` / `.markdown` 成为 sources；其它 selected paths 发布拒绝 Finding。direct targets 仅供 resolution，不扩大 source selection。
+- `findingPolicy` 为 `blocking | non-blocking`，默认 `non-blocking`，只决定本 Check 的普通链接 Finding 是否导致失败，不改写 Run、aggregation 或 Gate outcome；Records 与计数不随 policy 改变。
 - `requireExistingTargets` 控制缺失 direct local target 是否是 finding。
 - `validateSameDocumentAnchors` / `validateCrossDocumentAnchors` 分别控制当前文档与直接 Markdown target 的 heading
   lookup。
 - `rootExternalTargetMode` 为 `ignore | report | validate`；只有显式 `validate` 才授权 bounded root-external target I/O。
 - `requireNonEmptyDirectories` 启用时最多读取 direct directory 的一个 entry，不递归遍历。
+- `cache` 默认 `{ enabled: false }`，不访问 cache filesystem，且不能带 `directory`。启用 branch 必须为
+  `{ enabled: true, directory }`，其中 directory 是非空、无 U+0000 的 host-absolute path；安全与失败行为见 [Parse-facts cache](#parse-facts-cache)。
 - `limits` 限制单文档 bytes、全部 semantic occurrences 与 direct target reads；constructor 会补齐该 branch 中省略的
   fields。`maxMarkdownBytes` 不得超过 `16_777_216`，`maxOccurrences` 不得超过 `100_000`，
   `maxTargetReads` 不得超过 `10_000`。
@@ -69,13 +110,24 @@ const documentationLinks = markdownLinkValidation({
 });
 ```
 
+### Parse-facts cache
+
+启用后，cache 在调用方指定的 absolute directory 保存可删除的 Markdown parse facts；调用方负责目录容量与删除。
+它不是输出目录，也不提供机密性或防篡改保护；不愿复制到本地状态的 Markdown 不应启用 cache。
+
+命中只避免重复计算 parse facts；每次仍用当前 selection、Markdown bytes 与 target policy 形成 Finding、Record 和 outcome，
+不改变 Check ID 或 finding policy。无法恢复 facts 时 fresh-parse；写入失败只影响后续复用，不改变本次结果或任何发布字段。
+publication 开始前取消不会启动写入；append 开始后会等待完成。cache 不缓存 settlement，也不保证跨进程协调、持久性或自动清理。
+
 ## 工作原理
 
-Check 验证 options，收集 Markdown source paths，每份 source decode / parse 一次，再处理 supported inline、
-reference 与 autolink occurrences。完整 selected paths 先按 `.md` / `.markdown` suffix 分为 accepted/rejected，每个
-rejected path 产生 supplemental Record，只有 accepted path 成为 source。target file、directory 与 GitHub-priority heading
-anchor 按上面 policy 做 bounded validation；每个 link finding 产生另一种 supplemental Record。direct target 可以参与当前
-occurrence validation，source discovery 始终由 `files` selection 决定。
+Check 先验证 options，按本页 suffix 规则完整分类 selected paths，为 rejected paths 发布 Records，再解析 accepted sources。
+对 file、directory 与 GitHub-priority heading anchor 按 policy 做 bounded validation；每个普通链接 Finding 另发 Record。
+
+一次 invocation 内，同一 canonical Markdown target 的成功 parsed headings 可以被多个 cross-document anchor occurrence
+复用。它只复用首次成功 snapshot：target 随后变化时，本次 invocation 继续使用该 snapshot；target failure 不被 memoize。每个
+occurrence 仍独立完成 destination classification、containment 与 endpoint probe，并且在 memo lookup 前消耗一个
+`maxTargetReads` 额度。因此 `targetReadCount` 和 limit 仍是 logical occurrence 计数，不是 physical file-read 计数。
 
 受支持 occurrence 包含 inline link/image、已定义的 full/collapsed/shortcut reference、explicit autolink 和选定的 GFM
 autolink literal。YAML front matter、code/fenced code、HTML attribute、普通 prose URL 与 undefined reference 不进入本
@@ -84,9 +136,8 @@ Check 的 occurrence 集合。HTTP(S)、`mailto:` 与其它非本地 target 只
 ## 效果与结果
 
 没有 normal link finding 时 outcome 为 `passed`；有 normal link finding 时，`findingPolicy: "blocking"` 为 `failed`，
-`findingPolicy: "non-blocking"` 为 `passed`。input rejection 固定 non-blocking，不受该 policy 影响。两种 finding policy 都
-保留相同的 final data 与每 finding 一条 Record；blocking link finding 附带 `invalid-local-links` error message，
-non-blocking link finding 附带同 code 的 warning message。正常 final data 恰为：
+`findingPolicy: "non-blocking"` 为 `passed`。input rejection 固定 non-blocking，不受该 policy 影响。
+两种 policy 保留相同 final data 与每 Finding 一条 Record。正常 final data 恰为：
 
 ```ts
 {
@@ -99,8 +150,9 @@ non-blocking link finding 附带同 code 的 warning message。正常 final data
 ```
 
 `occurrenceCount` 包含所有 parser-semantic occurrences，包括没有进入 local target validation 的项；
-`targetReadCount` 统计进入 direct endpoint validation 的 occurrence；`findingCount - rejectedInputCount` 是 normal link
-finding 数量并且不超过 `occurrenceCount`。每个 normal link finding 恰好形成一条 Record，data 恰为：
+`targetReadCount` 统计进入 direct endpoint validation 的 logical occurrence（包括 target-memo hit）；`findingCount -
+rejectedInputCount` 是 normal link finding 数量并且不超过 `occurrenceCount`。每个 normal link finding 恰好形成一条 Record，data
+恰为：
 
 ```ts
 {
@@ -139,9 +191,12 @@ path 或 fragment。
 ```
 
 blocking finding 的 `failed` outcome 携带 `invalid-local-links` error message；non-blocking finding 的 `passed` outcome
-携带同 code 的 warning message；两者都引导调用方检查 Records 的 source range、target 与 reason。存在 rejected input 时
-另附一条 `input-rejected` warning，只汇总数量而不省略逐路径 Record。由本 Check 结算的 `unavailable` 使用对应
-`reason.code` 提供可操作 error message；无 Finding 的 `passed` 与 `not-applicable` 不合成人为提示。
+携带同 code 的 warning message。`markdownLinkValidation` 的 detail messages 先按 normal link、再按 input rejection 的稳定
+顺序：normal 摘要只含 source project-relative path、start line/column、occurrence kind 与封闭 reason，不复制 target；rejection
+摘要只含项目相对 path。存在 rejected input 时仍先附 `input-rejected` 数量 warning；完整 source range、safe target 与 reason
+仍从 Records 读取。通用的 terminal Finding 呈现与 Run progress 预览边界见
+[呈现 Check Finding](../guides/presenting-findings.md)。由本 Check 结算的 `unavailable` 使用对应 `reason.code` 提供可操作
+error message；无 Finding 的 `passed` 与 `not-applicable` 不合成人为提示。
 
 用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseMarkdownLinkValidationData(value)` 验证 final data。两者返回
 `MarkdownLinkValidationFinalData`；Records 与原因可用 `MarkdownLinkValidationRecordData`、
@@ -154,39 +209,32 @@ blocking finding 的 `failed` outcome 携带 `invalid-local-links` error message
 selected path 数量为零时结算为 `not-applicable / no-eligible-input`。selected 非空但全部 rejected 时，不解析 source，直接以
 带 final data、Records 与 warning 的 `passed` 结算。`unavailable.reason.code` 使用以下受控值：
 
-| `reason.code` | 触发边界与调用方检查项 |
-| --- | --- |
-| `invalid-options` | constructor 返回后形成的 replacement options 不是完整 closed resolved shape；重新调用 `markdownLinkValidation(options)` 或恢复完整字段。 |
-| `project-root-unavailable` | project root 无法 canonicalize；检查路径存在性与访问权限。 |
-| `source-unavailable` | source collection、读取、decode 或 containment 失败；检查 source 与 file-selection 来源。 |
-| `source-too-large` | 某个 selected Markdown source 超过 `maxMarkdownBytes`。 |
-| `markdown-parse-failed` | selected source 无法形成完整 parser facts。 |
-| `invalid-local-destination` | local destination 无法按受支持的 path/URI grammar 安全解析。 |
-| `target-unavailable` | target containment probe、I/O、decode、parse 或 directory read 失败；Markdown anchor target 超过 `maxMarkdownBytes` 也属于此分支。 |
-| `occurrence-limit-exceeded` | semantic occurrence 总数超过 `maxOccurrences`。 |
-| `target-read-limit-exceeded` | direct endpoint validation work 超过 `maxTargetReads`。 |
-| `cancelled` | invocation signal 取消本 Check；不要把结果解释为 clean validation。 |
+| `reason.code`                | 触发边界与调用方检查项                                                                                                                   |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `invalid-options`            | constructor 返回后形成的 replacement options 不是完整 closed resolved shape；重新调用 `markdownLinkValidation(options)` 或恢复完整字段。 |
+| `project-root-unavailable`   | project root 无法 canonicalize；检查路径存在性与访问权限。                                                                               |
+| `source-unavailable`         | source collection、读取、decode 或 containment 失败；检查 source 与 file-selection 来源。                                                |
+| `source-too-large`           | 某个 selected Markdown source 超过 `maxMarkdownBytes`。                                                                                  |
+| `markdown-parse-failed`      | selected source 无法形成完整 parser facts。                                                                                              |
+| `invalid-local-destination`  | local destination 无法按受支持的 path/URI grammar 安全解析。                                                                             |
+| `target-unavailable`         | target containment probe、I/O、decode、parse 或 directory read 失败；Markdown anchor target 超过 `maxMarkdownBytes` 也属于此分支。       |
+| `occurrence-limit-exceeded`  | semantic occurrence 总数超过 `maxOccurrences`。                                                                                          |
+| `target-read-limit-exceeded` | direct endpoint validation work 超过 `maxTargetReads`。                                                                                  |
+| `cancelled`                  | invocation signal 取消本 Check；不要把结果解释为 clean validation。                                                                      |
 
 这些边界不发布 partial link-finding Records，也不提供 final data；若 selected classification 已完成，已发布的
-rejected-input Records 与对应 warning 仍保留。通用 preflight 语法见
-[options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+rejected-input Records 与对应 warning 仍保留。通用 preparation 语法见
+[options preparation 与 execution](../api-mechanics.md#options-preparation-与-execution)。
 
 ## I/O 与安全边界
 
 source I/O scope 只包含通过 `.md` / `.markdown` eligibility 的 accepted paths；rejected path 不读取内容。resolver I/O scope
-是本地 filesystem，HTTP、DNS、TLS 与 redirect request 数为零。默认 `report` mode 对 root-external
-target 形成 finding，显式 `validate` mode 授权 bounded read。published facts 排除 raw external absolute path、target
-bytes 与 remote credentials。
-
-## 最小用法
+是本地 filesystem，HTTP、DNS、TLS 与 redirect request 数为零。默认 `report` mode 对 root-external target 形成 finding，显式
+`validate` mode 授权 bounded read。published facts 排除 raw external absolute path、target bytes 与 remote credentials。
 
-```ts
-import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
-const result = await run(defineConfig({ checks: [markdownLinkValidation()] }));
-```
+启用 `cache` 会额外访问调用方指定 directory，并可能写入上文所列 source-derived parse facts；它不改变 published facts，
+也不把 cache directory 当作 security boundary。调用方应仅传入自己信任、可删除的 absolute directory。
 
 ## 适用边界
 
-该 Check 只评估本机 target 与 heading-anchor integrity，不评估 remote URL reachability 或 HTML attribute links。项目需要
-这些能力时，应另外提供明确拥有网络或 HTML parsing policy 的 Check；当前 `markdownLinkValidation` 不会隐式扩展到这些
-输入。
+该 Check 不评估 remote URL reachability 或 HTML attribute links；需要时另配拥有明确网络或 HTML parsing policy 的 Check。