@zxyycom/vibe-check 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # Vibe Check
 
-Vibe Check 是面向 Bun 项目的 TypeScript 质量检查库。你可以直接使用随包提供的代码、JSON、Schema、Markdown 和维护检查，也可以把项目自己的规则写成 Check，然后在项目脚本、测试或 CI 中获得结构化结果。
+Vibe Check 是通用 TypeScript 质量门禁工具，提供可组合 Check、类型安全 API 和结构化结果。你可以直接使用随包提供的代码、JSON、Schema、Markdown 和维护检查，也可以把项目自己的规则写成 Check，然后在项目脚本、测试或 CI 中运行它们。
 
 所有公开能力都从 `@zxyycom/vibe-check` package root 导入。Vibe Check 不要求额外的配置文件，也不提供 CLI：检查内容、组合方式和运行时机都由你的 TypeScript 代码决定。
 
@@ -10,16 +10,59 @@ Vibe Check 是面向 Bun 项目的 TypeScript 质量检查库。你可以直接
 npm install @zxyycom/vibe-check
 ```
 
-npm 负责安装 package；应用代码和质量脚本使用 **Bun `>=1.3.14`** 执行。安装完成后，可以用 `bun run <file>` 运行下面的示例。
+npm 负责安装 package；应用代码和质量脚本的最低运行要求是 **Node `>=24.18`**。安装完成后，可以用 `node <file>` 运行下面的示例。
+
+升级前查看随包的[变更日志](./docs/changelog.md)，确认对应版本的变化与必要调整。
+
+## 随包提供的 Check
+
+如果项目需要的是常见质量检查，可以先从以下函数开始，而不必自己实现 `execute`。除 `maintenanceReminders(entries)` 与 `secretDetection({ files })` 有必填输入外，其余函数都可以无参调用；每份指南都包含最小用法、options、默认值、结果和安全边界。
+
+| 你想检查什么 | 使用的导出 | 额外环境准备 |
+| --- | --- | --- |
+| 重复代码 | [`duplicateDetection(options?)`](./docs/checks/duplicate-detection.md) | 无需另装分析器。 |
+| 文件代码行指标 | [`fileMetrics(options?)`](./docs/checks/file-metrics.md) | 环境中有兼容精确 SCC 4.0.0 输出契约的 `scc` command。 |
+| 函数规模、复杂度、最大嵌套和参数数量 | [`functionMetrics(options?)`](./docs/checks/function-metrics.md) | 无需另装分析器。 |
+| JSON 语法和输入范围 | [`jsonValidation(options?)`](./docs/checks/json-validation.md) | 无。 |
+| JSON 与 Schema 的匹配关系 | [`jsonSchemaValidation(options?)`](./docs/checks/json-schema-validation.md) | 使用远程 Schema 时，需显式允许对应 HTTPS source 并具备网络访问条件。 |
+| Markdown 结构与明确内容缺陷 | [`markdownLint(options?)`](./docs/checks/markdown-lint.md) | 无。 |
+| 本地 Markdown 链接与锚点 | [`markdownLinkValidation(options?)`](./docs/checks/markdown-link-validation.md) | 无。 |
+| 基于 Git 历史的维护提醒 | [`maintenanceReminders(entries)`](./docs/checks/maintenance-reminders.md) | 项目根目录是 Git repository，且环境可以执行 `git`。 |
+| 高置信 PEM private key | [`secretDetection({ files })`](./docs/checks/secret-detection.md) | 无需另装分析器。 |
+
+### 为随包 Check 声明项目行为
+
+八个 object-policy 构造器都在原有顶层 options 接受领域 policy 和项目声明。`maintenanceReminders` 保留
+`maintenanceReminders(entries)`，并增加包含 `entries` 的 object input；为同类 Check 创建多个实例时，直接提供 `checkId`。
+
+```ts
+import { defineConfig, fileMetrics } from "@zxyycom/vibe-check";
+
+const definition = defineConfig({
+  checks: [
+    fileMetrics({
+      checkId: "source-file-metrics",
+      enabledByFlags: { when: "source-changed" },
+      codeAreas: { source: { files: { include: ["src/**/*.ts"] } } }
+    }),
+    fileMetrics({
+      checkId: "test-file-metrics",
+      codeAreas: { tests: { files: { include: ["test/**/*.ts"] } } }
+    })
+  ]
+});
+```
+
+`PackageCheckAuthoringOptions` 可作为可复用的项目声明片段从 package root 导入。构造器返回原生 typed
+Check：项目字段成为 Check 声明，领域字段才形成 `.options` 和 execution `context.options`。完整字段、默认、
+关系与验证责任见 [API 机制](./docs/api-mechanics.md#随包-check-的构造器项目声明)；每个领域字段见对应 Check 指南。
+
+`duplicateDetection`、`fileMetrics`、`functionMetrics`、`markdownLint` 和 `markdownLinkValidation` 默认把普通 Finding 作为 non-blocking 警告保留下来；需要让 Finding 直接使 Check 失败时，在对应 options 中设置 `findingPolicy: "blocking"`。文件选择、阈值、外部工具和具体结果字段以各 Check 指南为准。
 
 ## 自定义 Check 快速开始
 
 下面的 `quality.ts` 展示一条完整的最小路径：定义 bundle 大小规则、运行它，并确认 Check 通过。为使示例能够独立运行，`actualBytes` 使用固定输入；接入项目时，把这部分替换为项目真实的测量逻辑即可。
 
-- `defineCheck(...)` 定义一项检查，以及通过或失败时要返回的数据。
-- `defineConfig(...)` 把一项或多项 Check 组成可重复运行的 Project Definition。
-- `run(...)` 执行 Definition，并返回本次运行的结果。
-
 示例保留默认的进度输出，但关闭 machine publication，因此第一次运行不会写入 `run.json` 或 `records.ndjson`：
 
 ```ts
@@ -28,7 +71,7 @@ import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
 const bundleSize = defineCheck({
   checkId: "bundle-size",
   displayName: "Bundle size",
-  execution() {
+  execute() {
     const actualBytes = 82_000;
     const maximumBytes = 100_000;
     const data = {
@@ -61,94 +104,55 @@ if (outcome?.status !== "passed" || outcome.data.actualBytes !== 82_000) {
 运行它：
 
 ```sh
-bun run quality.ts
+node quality.ts
 ```
 
 `RunResult.kind === "completed"` 表示这次 Run 已经完整结算，不等于其中每项 Check 都通过。示例继续读取 `bundle-size` 的 `outcome.status`，并在结果不符合预期时让脚本失败。
 
-## 随包提供的 Check
+## 运行、配置与读取结果
 
-如果项目需要的是常见质量检查，可以先从以下函数开始，而不必自己实现 `execution`。除 `maintenanceReminders(entries)` 必须接收提醒条目外，其余函数都可以无参调用；每份指南都包含最小用法、options、默认值、结果和安全边界。
+`defineConfig(...)` 定义可复用的 Checks、options、依赖、scheduler 和默认 outputs；`run(definition, controls?)` 的第二个参数只设置本次根目录、flags、取消、产物与日志目标、output overrides 和可选的本地 aggregation 函数。Controls 不能替换 Check 或 scheduler；字段位置和覆盖规则见 [API 机制](./docs/api-mechanics.md#参数应该放在哪里)。
 
-| 你想检查什么 | 使用的导出 | 运行前提 |
-| --- | --- | --- |
-| 重复代码 | [`duplicateDetection(options?)`](./docs/checks/duplicate-detection.md) | package 使用随安装依赖提供的兼容 jscpd v5。 |
-| 文件代码行指标 | [`fileMetrics(options?)`](./docs/checks/file-metrics.md) | 环境中有兼容 SCC 3.7.0 输出契约的 `scc` command。 |
-| 函数规模、复杂度和参数数量 | [`functionMetrics(options?)`](./docs/checks/function-metrics.md) | 环境中有兼容 Lizard 1.23 输出契约的 `lizard` command。 |
-| JSON 语法和输入范围 | [`jsonValidation(options?)`](./docs/checks/json-validation.md) | 只读取本地文件，不执行 command 或网络请求。 |
-| JSON 与 Schema 的匹配关系 | [`jsonSchemaValidation(options?)`](./docs/checks/json-schema-validation.md) | 默认离线；只有显式允许的 HTTPS source 才会触发网络请求。 |
-| 本地 Markdown 链接与锚点 | [`markdownLinkValidation(options?)`](./docs/checks/markdown-link-validation.md) | 只读取 policy 允许的本地路径，不执行 command 或网络请求。 |
-| 基于 Git 历史的维护提醒 | [`maintenanceReminders(entries)`](./docs/checks/maintenance-reminders.md) | 项目根目录是 Git repository，且环境可以执行 `git`。 |
-
-`duplicateDetection`、`fileMetrics`、`functionMetrics` 和 `markdownLinkValidation` 默认把普通 Finding 作为 non-blocking 警告保留下来；需要让 Finding 直接使 Check 失败时，在对应 options 中设置 `findingPolicy: "blocking"`。文件选择、阈值、外部工具和具体结果字段以各 Check 指南为准。
-
-## 自定义 Check API
-
-只使用随包 Check 时，可以跳过本节。需要表达项目自己的规则时，通常只需要定义 Check、组成 Definition、运行并读取结果；preflight、依赖调度、waiver 对账、聚合和取消等进阶能力放在[深入 API 机制](./docs/api-mechanics.md)中。
+默认最多并行运行四个 Check，显示进度并把 machine files 写入 `artifacts/vibe-check`；diagnostic logging 默认关闭。上例显式关闭 machine publication。配置方法见[输出指南](./docs/guides/run-outputs.md)与[调度指南](./docs/guides/scheduling.md)。
 
-### 定义 Check
+先判断 `RunResult.kind`；`completed` 和 `output` 才同时提供完整 facts 与 `aggregate`，随后再按 `checkId` 读取 `snapshot.checks[].outcome` 的 `passed`、`failed`、`not-applicable` 或 `unavailable`。执行阶段取消也有 snapshot，但没有 aggregate。省略定制函数时，aggregate 仅在有效 Check 列表非空且全部 `passed` 时为 `passed`，否则为 `failed`。`completed` 不代表质量通过；CI 可读取这个严格默认值，或在 [`checkAggregation`](./docs/api-mechanics.md#runcontrols-与-check-aggregation) 中同步解释同一有效列表，再决定退出码。
 
-`defineCheck(value)` 接受一个普通 Check object，并保留 `checkId`、options 和 final data 的 TypeScript inference。常用字段如下：
+## 按任务继续阅读
 
-| 字段 | 用途 |
-| --- | --- |
-| `checkId` | 在同一 Definition 中唯一的稳定标识；用于查找 outcome、Record、message 和 duration。 |
-| `displayName` | 进度和人读结果中显示的名称。 |
-| `execution(context)` | 执行检查并返回一个 terminal outcome。省略时，当前节点只用于组织子 `checks`。 |
-| `options` | 当前 Check 的配置；Run 会把准备后的只读副本交给 `context.options`。 |
-| `checks` | 可选的子 Check 列表，用于组织一组相关规则。 |
+只读当前任务需要的专题；精确 overload、泛型推断和字段 JSDoc 以安装包中的 `types/**.d.ts` 为准。
 
-`execution` 可以同步返回，也可以返回 `Promise`。它通过 `context` 读取当前 options、project root、flags、已声明依赖的数据、取消 signal，并可用 `records.report(...)` 保存不决定终态的补充事实。
+- [从项目质量目标构建 Gate](./docs/guides/building-project-gate.md)：从最小入口出发，按实际问题接入脚本、共享准备、增量选择、自建缓存和诊断。
+- [API 机制](./docs/api-mechanics.md)：Run 生命周期、组合继承、结果与 aggregation。
+- [选择回调位置](./docs/guides/callbacks.md)：确定执行前、检查中、显示时或结束后的接入点。
+- [自定义 Check](./docs/guides/extending-check-lifecycle.md)：options 准备、callback context、Records 与协作取消。
+- [执行外部命令的 Check](./docs/guides/command-check.md)：以单一 executable 和独立 arguments 接入 exit-status command，配置 environment、输出与终态边界。
+- [Check 依赖与类型化数据](./docs/guides/check-dependencies.md)：`dependsOn` / `observes`、读取授权与 provider parser。
+- [Run 输出与诊断](./docs/guides/run-outputs.md)：输出配置、progress、日志与失败处理。
+- [调度 Check](./docs/guides/scheduling.md)：并发资源、准入策略与终态观察。
+- [机器输出契约](./docs/output.md)：供其他工具读取 `run.json`、`records.ndjson` 与 schemas。
 
-| 返回状态 | 何时使用 |
-| --- | --- |
-| `passed` | 检查完成且满足规则；同时返回主要 final `data`。 |
-| `failed` | 检查完成但不满足规则；同时返回主要 final `data`。 |
-| `not-applicable` | 当前输入没有适用的工作；可以附带 reason。 |
-| `unavailable` | 无法形成可信结果；必须附带 reason。 |
+以下可选工具由项目代码或自定义 Check 显式调用：
 
-final `data` 和 supplemental Record 使用 object-shaped canonical JSON。Check 可以附带有序的人读 `messages`，但通用 API 不保证每个结果都有 message。
-
-### 组成 Project Definition
-
-`defineConfig({ checks, ... })` 组成可重复运行的 Project Definition，并补齐未声明的默认值。最常调整的默认项是：
-
-| 配置 | 默认值 | 效果 |
+| 目的 | 工具与接入方式 | 详解 |
 | --- | --- | --- |
-| `outputs.progressRendering.enabled` | `true` | 在终端呈现 Check 生命周期与汇总。 |
-| `outputs.machinePublication.enabled` | `true` | 把 `run.json` 和 `records.ndjson` 写入 `artifacts/vibe-check`。 |
-| `outputs.diagnosticLogging.enabled` | `false` | 需要排障时写入 invocation-specific 日志。 |
-| `scheduler.maxParallel` | `4` | 限制最外层 Check 并行数。 |
-
-`outputs` 和 `scheduler` 都可以只覆盖需要改变的 nested field；同一份 Definition 可以安全地传给多次 `run(...)`。
+| 按一份完整 selection 收集项目文件 path | `collectProjectFiles(...)` 在普通项目代码或 custom Check 内返回冻结的 relative path 快照 | [收集项目文件](./docs/guides/collecting-project-files.md) |
+| 按完整语义 key 复用本地 JSON 计算 | `cacheJsonByKey(...)` 在普通项目代码或 Check 内返回一次调用的缓存结果 | [缓存计算结果](./docs/guides/cache-results.md) |
+| 取得独立 JSON 副本、生成确定性表示，或检查含回调的配置结构 | 两组公开 Core 工具分别负责 JSON 规范化/序列化与外层结构快照，无需创建 Check 或 Run | [Core 数据工具](./docs/guides/data-boundaries.md) |
+| 对账完整 Finding 集合与 waiver audit | `reconcileFindingWaivers(...)` 在 Finding 形成后返回 disposition 与 audit | [对账 Finding waiver](./docs/guides/finding-waivers.md) |
+| 生成有限的 Finding 人读摘要 | `presentCheckFindings(...)` 返回 `CheckMessage[]`，由 producing Check 附到自己的 terminal result | [呈现 Check Finding](./docs/guides/presenting-findings.md) |
+| 在不执行 Check 的前提下分析静态 admission 分支 | `createAdmissionGraph(...)` 独立创建 immutable simulation，不需要 `run(...)` 或 custom policy | [模拟 AdmissionGraph](./docs/guides/simulating-admission.md) |
+| 为重复 Run 准备基于本地时长 history 的选择策略 | `createLearnedCriticalPathStrategy(...)` 的返回值接入 `scheduler.admissionPolicy` 的 custom strategy | [learned critical-path strategy](./docs/guides/learned-scheduling.md) |
 
-### 运行并读取结果
-
-`run(definition, controls?)` 执行一次独立 invocation。常用 controls 包括 `projectRoot`、`flags`、`signal` 和仅对本次运行生效的 `outputs` overrides。
-
-读取结果时分两层判断：
-
-1. 先读取 `RunResult.kind`，确认 invocation 是完整结算、配置错误、规划失败、输出失败、执行失败还是被取消。
-2. 对有 snapshot 的结果，按 `checkId` 查找 `snapshot.checks[].outcome`，再处理 `passed`、`failed`、`not-applicable` 或 `unavailable`。
-
-合法运行中，即使某项 Check 返回 `failed`，Run 仍可能是 `kind: "completed"`。如果 CI 需要因质量 Finding 退出非零状态，调用方必须像快速开始那样显式判断目标 outcome，或配置并读取 invocation-level aggregation。
-
-## 输出与进阶用法
-
-- [深入 API 机制](./docs/api-mechanics.md)说明 options preflight、依赖、组合、aggregation、finding waiver、cancellation 和 output failure 边界。
-- [机器输出契约](./docs/output.md)说明 `run.json`、`records.ndjson` 和对应 schemas；只有需要把结果交给其他工具时才需要读取它。
-- 精确 overload、泛型推断和字段 JSDoc 以安装包中的 `types/**.d.ts` 为准。
+各随包 Check 的 `parse…Data` 导出用于解析该 Check 的 final data；完整签名与类型见相应 Check 指南及 installed declarations。
 
 ## 包内结构与调试
 
 业务代码始终从 `@zxyycom/vibe-check` 导入。安装包中的 `index.mjs` 是公开 runtime entry，`types/**.d.ts` 提供 TypeScript declarations；source maps、`src/**.ts` 和可读的 `dist/esm/**.mjs` 用于堆栈定位与实现检查，不是额外的 public import path。
 
-安装包还包含机器输出文档、v4 run / Record schemas 和一组完整 artifact example，便于需要消费机器结果的工具核对实际 bytes。
-
 ## 分发与兼容范围
 
-npm 只负责分发和安装 package；受支持的产品 host 是 **Bun `>=1.3.14`**。通过 npm 安装不表示 Node.js runtime 已受支持。
-
 当前 public contract 只有 `@zxyycom/vibe-check` package root 的程序化 API。CLI、`bin`、plugin API、CommonJS/browser entry 和 subpath imports 都不在支持范围内。
 
-`0.0.x` patch 之间不承诺 package-level 兼容。项目应提交 lockfile，并在升级前检查对应版本的变更。Vibe Check 使用 MIT License，完整许可文本随 package 一起安装。
+`0.0.x` patch 之间不承诺 package-level 兼容。项目应提交 lockfile，并在升级前检查对应版本的变更。
+
+随包法律材料包括根 `LICENSE` 中的 Vibe Check MIT 文本，以及 `licenses/` 中的分析器翻译归属说明、第三方许可原文与来源记录。npm 依赖作为独立包安装，其许可声明及随附法律材料由各依赖包提供。

package/dist/esm/check/check.mjs

@@ -1,5 +1,9 @@
+import { registerHandoffProviderIdentity } from "./handoff-provider-identity.mjs";
 export { inherit, isInheritedCheckCollection, snapshotInheritedCheckCollection } from "./inherited-collection.mjs";
 export function defineCheck(value) {
+    if (value.handoff === true) {
+        registerHandoffProviderIdentity(value);
+    }
     return value;
 }
 //# sourceMappingURL=check.mjs.map

package/dist/esm/check/check.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"check.mjs","sourceRoot":"","sources":["../../../src/check/check.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,OAAO,EACP,0BAA0B,EAC1B,gCAAgC,EACjC,MAAM,2BAA2B,CAAC;AAuenC,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import type { CanonicalJsonObject, CanonicalJsonValue } from \"../data-boundary/canonical-json.ts\";\nimport type { InheritableCheckCollection } from \"./inherited-collection.ts\";\n\nexport {\n  inherit,\n  isInheritedCheckCollection,\n  snapshotInheritedCheckCollection\n} from \"./inherited-collection.ts\";\nexport type {\n  InheritCheckCollectionInput,\n  InheritableCheckCollection,\n  InheritedCheckCollection\n} from \"./inherited-collection.ts\";\n\n/** Check 无法给出 final data 时返回的受控 reason code。 */\nexport type CheckReason = Readonly<{\n  /** 由 owning Check 定义、供调用方诊断的稳定 code。 */\n  readonly code: string;\n}>;\n\n/** `not-applicable` Check result 的可选 reason。 */\nexport type CheckNotApplicableReason = CheckReason;\n/** author callback 明确返回 `unavailable` 时必须提供的 reason。 */\nexport type CheckDeclaredUnavailableReason = CheckReason;\n\n/** `unavailable` Check outcome 的 reason；可列出导致当前 Check 不可用的上游 Check。 */\nexport type CheckUnavailableReason = Readonly<{\n  /** 由当前 Check 或 Product 边界给出的受控原因。 */\n  readonly code: string;\n  /** 仅在上游关系有助于定位时给出的相关 Check IDs。 */\n  readonly checkIds?: readonly string[];\n}>;\n\n/** 终端 Check message 的 presentation severity。 */\nexport type CheckMessageLevel = \"info\" | \"warning\" | \"error\";\n\n/** 由 Check author 附加到 terminal result 的补充消息。 */\nexport interface CheckMessage {\n  /** 人读 presentation 使用的 severity。 */\n  readonly level: CheckMessageLevel;\n  /** owning Check namespace 内的稳定 message code。 */\n  readonly code: string;\n  /** 非空消息正文；Product 保留 author 提供的字符串。 */\n  readonly message: string;\n}\n\n/** 可附加到每个 {@link CheckResult} branch 的有序 terminal messages。 */\nexport interface CheckResultMessages {\n  /** 省略、`undefined` 或空数组都表示没有 supplemental messages。 */\n  readonly messages?: readonly CheckMessage[];\n}\n\n/** 已结算 Check 在人读 progress 中的可见性。 */\nexport type CheckVisibility = \"always\" | \"attention\";\n\n/**\n * Check callback 的 terminal result。\n *\n * @typeParam FinalData - `passed` 或 `failed` 时保留为 canonical final data 的业务对象。\n * @remarks `not-applicable` 与 `unavailable` 不携带 final data；普通 callback、Record 或取消失败由\n * Product 转换为 `unavailable`，而不是抛出为 Run 的成功结果。\n */\nexport type CheckResult<FinalData extends object = object> = Readonly<\n  (\n    | {\n        /** Check 已产生通过的 final data。 */\n        readonly status: \"passed\";\n        /** 此 Check 的主要终态事实。 */\n        readonly data: FinalData;\n      }\n    | {\n        /** Check 已产生失败的 final data。 */\n        readonly status: \"failed\";\n        /** 此 Check 的主要终态事实。 */\n        readonly data: FinalData;\n      }\n    | {\n        /** Check 在当前 invocation 中不适用。 */\n        readonly status: \"not-applicable\";\n        /** 不适用的可选受控原因。 */\n        readonly reason?: CheckNotApplicableReason;\n      }\n    | {\n        /** Check 不能提供 terminal data。 */\n        readonly status: \"unavailable\";\n        /** 不可用的受控原因。 */\n        readonly reason: CheckDeclaredUnavailableReason;\n      }\n  ) &\n    CheckResultMessages\n>;\n\n/** 已 materialize 到 Core snapshot 的 Check terminal outcome。 */\nexport type CheckOutcome = Readonly<\n  | {\n      /** 已 materialize 的通过 outcome。 */\n      readonly status: \"passed\";\n      /** 已 canonicalize 的 primary final fact。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** 已 materialize 的失败 outcome。 */\n      readonly status: \"failed\";\n      /** 已 canonicalize 的 primary final fact。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** 已 materialize 的不适用 outcome。 */\n      readonly status: \"not-applicable\";\n      /** 不适用的可选受控原因。 */\n      readonly reason?: CheckNotApplicableReason;\n    }\n  | {\n      /** 已 materialize 的不可用 outcome。 */\n      readonly status: \"unavailable\";\n      /** 包含相关 upstream Check IDs 的受控原因。 */\n      readonly reason: CheckUnavailableReason;\n    }\n>;\n\n/** 将 callback options 转为不可变观察值的递归 utility type。 */\nexport type DeepReadonly<T> = T extends string | number | boolean | null\n  ? T\n  : T extends readonly (infer Item)[]\n    ? readonly DeepReadonly<Item>[]\n    : T extends object\n      ? { readonly [Key in keyof T]: DeepReadonly<T[Key]> }\n      : never;\n\n/** callback 写入 supplemental Record 时的 Check-local identity。 */\ninterface RecordIdentityInput {\n  /** 在当前 Check 内唯一的 Record ID。 */\n  readonly id: string;\n}\n\n/** callback 写入 supplemental Records 的 Product-owned reporter。 */\ninterface CheckRecordReporter {\n  /** 记录一个补充事实；它不决定 Check 的 terminal status。 */\n  report(identity: RecordIdentityInput, data: object): void;\n}\n\n/** 读取已声明 dependency final data 时的失败原因。 */\nexport type DependencyReadError = Readonly<\n  | {\n      /** 当前 Check 未声明所请求的 dependency ID。 */\n      readonly code: \"dependency-not-declared\";\n      /** 被拒绝的 dependency ID。 */\n      readonly checkId: string;\n    }\n  | {\n      /** 已声明 upstream 没有可读取的 final data。 */\n      readonly code: \"upstream-data-unavailable\";\n      /** 没有 final data 的 direct dependency ID。 */\n      readonly checkId: string;\n      /** 阻止 readback 的 upstream terminal status。 */\n      readonly status: \"not-applicable\" | \"unavailable\";\n    }\n>;\n\n/** {@link CheckDependencies.get} 的受控 readback 结果。 */\nexport type DependencyReadResult = Readonly<\n  | {\n      /** 成功读取 direct dependency final data。 */\n      readonly ok: true;\n      /** 被读取的 direct dependency ID。 */\n      readonly checkId: string;\n      /** upstream 已结算为 `passed` 或 `failed` 的 status。 */\n      readonly status: \"passed\" | \"failed\";\n      /** 已与原对象脱离的上游依赖终态数据。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** dependency data 不可读取。 */\n      readonly ok: false;\n      /** 失败的授权或 upstream-data reason。 */\n      readonly error: DependencyReadError;\n    }\n>;\n\n/** 当前 Check 的已规范化直接 dependencies 的 data reader。 */\nexport interface CheckDependencies {\n  /**\n   * 读取一个直接 dependency 的 canonical final data。\n   *\n   * @returns 已声明且为 `passed`/`failed` 的 dependency 返回其 data；未声明或没有 final data 时返回\n   * `ok: false`，不会授权 transitive dependency。\n   */\n  get(checkId: string): DependencyReadResult;\n}\n\n/** callback 可读取的、由 Product 规范化的项目上下文。 */\nexport interface CheckProjectContext {\n  /** 本次 Run 使用的绝对项目根目录。 */\n  readonly root: string;\n  /** 已去重、排序的 caller-supplied flags。 */\n  readonly flags: readonly string[];\n}\n\n/**\n * Check callback 收到的 Product-owned execution context。\n *\n * @typeParam Options - 此 Check preflight 后传给 execution 的 options shape。\n */\nexport interface CheckExecutionContext<Options extends object> {\n  /** 读取当前 Check 的已声明 direct dependencies。 */\n  readonly dependencies: CheckDependencies;\n  /** 深度只读、canonical 的 invocation-local prepared Check options。 */\n  readonly options: DeepReadonly<Options>;\n  /** 已规范化的项目根与 flags。 */\n  readonly project: CheckProjectContext;\n  /** 写入 supplemental Records 的 reporter。 */\n  readonly records: CheckRecordReporter;\n  /** 本次 invocation 的 cancellation signal。 */\n  readonly signal: AbortSignal;\n}\n\n/**\n * 一个 Check 的 callback signature。\n *\n * @typeParam Options - callback 从 context 读取的 prepared options shape。\n * @returns terminal Check result 或其 Promise。\n */\nexport type CheckExecution<Options extends object = object> = (\n  this: void,\n  context: CheckExecutionContext<Options>\n) => CheckResult | Promise<CheckResult>;\n\n/**\n * 在 Check execution 前，可选地为本次 invocation 准备 options。\n *\n * @remarks `signal` 与同一次 callback execution 使用同一个 cancellation signal；实现应在可等待工作中\n * 协作退出，而不是留下悬挂 work。bivariant callback 保持具体 options Check 可进入普通递归 Check\n * collection；Product 仍只会用该 Check 自己的 authored options 调用它。精确结果见\n * {@link CheckPreflightResult}。\n */\nexport type CheckPreflight<\n  AuthoredOptions extends object = object,\n  PreparedOptions extends object = AuthoredOptions\n> = {\n  bivarianceHack(\n    this: void,\n    options: DeepReadonly<AuthoredOptions>,\n    signal: AbortSignal\n  ): CheckPreflightResult<PreparedOptions> | Promise<CheckPreflightResult<PreparedOptions>>;\n}[\"bivarianceHack\"];\n\n/**\n * Check-owned preflight 的判别结果。\n *\n * `failure/block` 不允许 fallback，直接以 owning reason 结算为 unavailable；`failure/continue` 必须给出\n * fallback 并继续 execution。两种进入 execution 的值都只属于本次 invocation，Product canonicalize/freeze\n * 后传递，不会改写 Definition 中 authored options。两个 failure 分支都必须给出 reason；continue reason\n * 是 Check-owned diagnostic identity，当前不会单独 materialize 为 outcome，调用方通过 messages 与后续\n * outcome 观察结果；block 物理上不含 fallback 字段。\n */\nexport type CheckPreflightResult<PreparedOptions extends object = object> = Readonly<\n  | {\n      readonly status: \"success\";\n      readonly preparedOptions: PreparedOptions;\n      readonly messages?: readonly CheckMessage[];\n    }\n  | {\n      readonly status: \"failure\";\n      readonly action: \"block\";\n      readonly reason: CheckDeclaredUnavailableReason;\n      readonly messages?: readonly CheckMessage[];\n    }\n  | {\n      readonly status: \"failure\";\n      readonly action: \"continue\";\n      readonly fallback: PreparedOptions;\n      readonly reason: CheckReason;\n      readonly messages?: readonly CheckMessage[];\n    }\n>;\n\n/**\n * 普通递归 Check authoring value 的共享字段。\n *\n * @typeParam AuthoredOptions - Definition 中的 declarative options shape。\n * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。\n * @remarks 该值可以同时有 `execution` 和 `checks`；只有 executable node 产生 final Check fact。\n */\ninterface CheckBase<AuthoredOptions extends object, PreparedOptions extends object> {\n  /** 在 Definition 内唯一的 stable Check ID。 */\n  readonly checkId: string;\n  /** 人读 progress 与 output 使用的非空名称。 */\n  readonly displayName: string;\n  /** Check-owned declarative options；默认 Check 的嵌套 branch 以普通对象组合替换。 */\n  readonly options?: AuthoredOptions;\n  /** 可执行节点的 callback；省略时此节点只承载递归 children。 */\n  execution?(\n    this: void,\n    context: CheckExecutionContext<PreparedOptions>\n  ): CheckResult | Promise<CheckResult>;\n  /** 继承 scheduling context 的 child Checks，不会单独形成 container result。 */\n  readonly checks?: readonly Check[];\n  /** 直接 prerequisite Check IDs，或对父 dependency collection 的显式 edit。 */\n  readonly dependsOn?: InheritableCheckCollection<string>;\n  /** 此 Check 及其 descendants 的最大并行预算。 */\n  readonly maxParallel?: number;\n  /** 共享资源名称，或对父 mutex collection 的显式 edit。 */\n  readonly mutex?: InheritableCheckCollection<string>;\n  /** 已结算 Check 的人读可见性；可执行节点默认 `always`。 */\n  readonly visibility?: CheckVisibility;\n}\n\n/**\n * 判断两个 options shape 是否互相可赋值；互相可赋值时 execution 不需要 preparation 转换。\n */\ntype HasSameOptionsShape<AuthoredOptions extends object, PreparedOptions extends object> = [\n  AuthoredOptions\n] extends [PreparedOptions]\n  ? [PreparedOptions] extends [AuthoredOptions]\n    ? true\n    : false\n  : false;\n\n/** Prepared shape 不同时，preflight 是建立安全转换的必填边界。 */\ntype CheckPreflightField<AuthoredOptions extends object, PreparedOptions extends object> =\n  HasSameOptionsShape<AuthoredOptions, PreparedOptions> extends true\n    ? Readonly<{ readonly preflight?: CheckPreflight<AuthoredOptions, PreparedOptions> }>\n    : Readonly<{ readonly preflight: CheckPreflight<AuthoredOptions, PreparedOptions> }>;\n\n/**\n * Project Definition 中的普通递归 Check authoring value。\n *\n * @typeParam AuthoredOptions - Definition 中的 declarative options shape。\n * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。\n * @remarks Definition 只闭合 authored JSON options；preflight 在同一 Run 的所有 execution 前作为全局\n * barrier 执行。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preflight；同形时可以省略。它不进入\n * declarative fingerprint 或 machine output。\n */\nexport type Check<\n  AuthoredOptions extends object = object,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckBase<AuthoredOptions, PreparedOptions> &\n  CheckPreflightField<AuthoredOptions, PreparedOptions>;\n\nexport type EmptyCheckOptions = Readonly<Record<never, never>>;\n\n/**\n * 防止宽泛的 parser 标注擦除 `PromiseLike`。canonical `then` field 可以保存 JSON data，\n * 但不能保存使该值成为 thenable 的 callable。\n */\ntype NonThenableData = Readonly<{ readonly then?: CanonicalJsonValue }>;\n\n/**\n * 将 canonical dependency data 还原为 provider final-data shape 的同步 parser。\n *\n * @typeParam FinalData - provider 在 `passed`/`failed` result 中声明的 final-data shape。\n * @remarks Product 不调用此 parser；provider 负责不受信任或跨版本 data 的业务验证。\n */\nexport type CheckDataParser<FinalData extends object = object> = (\n  this: void,\n  data: CanonicalJsonObject\n) => FinalData & NonThenableData;\n\ntype CheckAuthoringBase<\n  Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object\n> = Omit<CheckBase<AuthoredOptions, PreparedOptions>, \"checkId\" | \"execution\" | \"options\"> &\n  CheckPreflightField<AuthoredOptions, PreparedOptions> &\n  Readonly<{ readonly checkId: Id }>;\n\ninterface OrdinaryCheckFields<PreparedOptions extends object> {\n  execution?(\n    this: void,\n    context: CheckExecutionContext<PreparedOptions>\n  ): CheckResult | Promise<CheckResult>;\n  readonly parseData?: never;\n}\n\nexport type CheckWithOptions<\n  Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n  OrdinaryCheckFields<PreparedOptions> &\n  Readonly<{\n    readonly options: AuthoredOptions;\n  }>;\n\nexport type CheckWithoutOptions<Id extends string> = CheckAuthoringBase<\n  Id,\n  EmptyCheckOptions,\n  EmptyCheckOptions\n> &\n  OrdinaryCheckFields<EmptyCheckOptions> &\n  Readonly<{\n    readonly options?: never;\n  }>;\n\ninterface TypedCheckFields<PreparedOptions extends object, Parser extends CheckDataParser> {\n  /**\n   * 将 canonical runtime data 还原为 provider data。\n   *\n   * 启发式边界：同版本且受信任的 provider 若由测试保证 data shape，可仅将它实现为\n   * identity/type anchor。这不验证 JavaScript 或基于 cast 的 producer、历史或跨版本 artifact，\n   * 也不验证不受信任输入。\n   */\n  readonly parseData: Parser;\n\n  execution(\n    this: void,\n    context: CheckExecutionContext<PreparedOptions>\n  ): CheckResult<NoInfer<ReturnType<Parser>>> | Promise<CheckResult<NoInfer<ReturnType<Parser>>>>;\n}\n\nexport type TypedCheckWithOptions<\n  Id extends string,\n  AuthoredOptions extends object,\n  Parser extends CheckDataParser,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n  TypedCheckFields<PreparedOptions, Parser> &\n  Readonly<{\n    readonly options: AuthoredOptions;\n  }>;\n\nexport type TypedCheckWithoutOptions<\n  Id extends string,\n  Parser extends CheckDataParser\n> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> &\n  TypedCheckFields<EmptyCheckOptions, Parser> &\n  Readonly<{\n    readonly options?: never;\n  }>;\n\n/**\n * 定义一个 Check，同时保留 literal `checkId`、options 与 typed-provider parser 的 inference。\n *\n * @remarks 此函数负责 authoring inference；{@link run} 负责 Project Definition validation。\n * @example 定义带 options、Records 与 messages 的自定义 Check\n * ```ts\n * function hasValidLicensePolicyOptions(options: object): boolean {\n *   const denied: unknown = Reflect.get(options, \"denied\");\n *   return (\n *     Object.keys(options).length === 1 &&\n *     Object.hasOwn(options, \"denied\") &&\n *     Array.isArray(denied) &&\n *     denied.every((license) => typeof license === \"string\")\n *   );\n * }\n *\n * const licensePolicy = defineCheck({\n *   checkId: \"license-policy\",\n *   displayName: \"License policy\",\n *   options: { denied: [\"GPL-3.0-only\"] },\n *   preflight(options) {\n *     return hasValidLicensePolicyOptions(options)\n *       ? { status: \"success\", preparedOptions: options }\n *       : { status: \"failure\", action: \"block\", reason: { code: \"invalid-options\" } };\n *   },\n *   visibility: \"attention\",\n *   execution({ options, records, signal }) {\n *     if (signal.aborted) return { status: \"unavailable\", reason: { code: \"cancelled\" } };\n *\n *     const deniedCount = options.denied.length;\n *     if (deniedCount > 0) {\n *       records.report({ id: \"denied-license\" }, { count: deniedCount });\n *       return {\n *         status: \"failed\",\n *         data: { deniedCount },\n *         messages: [{ level: \"warning\", code: \"denied-license\", message: \"Denied licenses found.\" }]\n *       };\n *     }\n *     return { status: \"passed\", data: { deniedCount: 0 } };\n *   }\n * });\n * ```\n */\nexport function defineCheck<\n  const Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object = AuthoredOptions\n>(\n  value: CheckWithOptions<Id, AuthoredOptions, PreparedOptions>\n): CheckWithOptions<Id, AuthoredOptions, PreparedOptions>;\nexport function defineCheck<const Id extends string>(\n  value: CheckWithoutOptions<Id>\n): CheckWithoutOptions<Id>;\nexport function defineCheck<\n  const Id extends string,\n  AuthoredOptions extends object,\n  const Parser extends CheckDataParser,\n  PreparedOptions extends object = AuthoredOptions\n>(\n  value: TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>\n): TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>;\nexport function defineCheck<const Id extends string, const Parser extends CheckDataParser>(\n  value: TypedCheckWithoutOptions<Id, Parser>\n): TypedCheckWithoutOptions<Id, Parser>;\nexport function defineCheck(value: Check): Check {\n  return value;\n}\n"]}
+{"version":3,"file":"check.mjs","sourceRoot":"","sources":["../../../src/check/check.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AAEjF,OAAO,EACL,OAAO,EACP,0BAA0B,EAC1B,gCAAgC,EACjC,MAAM,2BAA2B,CAAC;AAmwBnC,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC3B,+BAA+B,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import type { CanonicalJsonObject, CanonicalJsonValue } from \"../data-boundary/canonical-json.ts\";\nimport type { InheritableCheckCollection } from \"./inherited-collection.ts\";\nimport type { CheckFlagEnablement } from \"./flag-enablement.ts\";\nimport type { CheckProjectContext } from \"./project-context.ts\";\nimport { registerHandoffProviderIdentity } from \"./handoff-provider-identity.ts\";\n\nexport {\n  inherit,\n  isInheritedCheckCollection,\n  snapshotInheritedCheckCollection\n} from \"./inherited-collection.ts\";\nexport type {\n  InheritCheckCollectionInput,\n  InheritableCheckCollection,\n  InheritedCheckCollection\n} from \"./inherited-collection.ts\";\n\n/** Check 无法给出 final data 时返回的受控 reason code。 */\nexport type CheckReason = Readonly<{\n  /** 由 owning Check 定义、供调用方诊断的稳定 code。 */\n  readonly code: string;\n}>;\n\n/** `not-applicable` Check result 的可选 reason。 */\nexport type CheckNotApplicableReason = CheckReason;\n/** author callback 明确返回 `unavailable` 时必须提供的 reason。 */\nexport type CheckDeclaredUnavailableReason = CheckReason;\n\n/** `unavailable` Check outcome 的 reason；可列出导致当前 Check 不可用的上游 Check。 */\nexport type CheckUnavailableReason = Readonly<{\n  /** 由当前 Check 或 Product 边界给出的受控原因。 */\n  readonly code: string;\n  /** 仅在上游关系有助于定位时给出的相关 Check IDs。 */\n  readonly checkIds?: readonly string[];\n}>;\n\n/** 终端 Check message 的 presentation severity。 */\nexport type CheckMessageLevel = \"info\" | \"warning\" | \"error\";\n\n/** 由 Check author 附加到 terminal result 的补充消息。 */\nexport interface CheckMessage {\n  /** 人读 presentation 使用的 severity。 */\n  readonly level: CheckMessageLevel;\n  /** owning Check namespace 内的稳定 message code。 */\n  readonly code: string;\n  /** 非空消息正文；Product 保留 author 提供的字符串。 */\n  readonly message: string;\n}\n\n/** 可附加到每个 {@link CheckResult} branch 的有序 terminal messages。 */\nexport interface CheckResultMessages {\n  /** 省略、`undefined` 或空数组都表示没有 supplemental messages。 */\n  readonly messages?: readonly CheckMessage[] | undefined;\n}\n\ntype HandoffForbidden = Readonly<{ readonly handoff?: never }>;\n\n/** Check Task 在 admission 到 settlement 期间持有的静态 named resource units。 */\nexport type CheckResourceClaims = Readonly<Record<string, number>>;\n\nexport type { CheckFlagCondition, CheckFlagEnablement } from \"./flag-enablement.ts\";\nexport type { ProjectChanges } from \"./project-changes.ts\";\nexport type { CheckProjectContext } from \"./project-context.ts\";\n\n/**\n * Check callback 的 terminal result。\n *\n * @typeParam FinalData - `passed` 或 `failed` 时保留为 canonical final data 的业务对象。\n * @remarks `not-applicable` 与 `unavailable` 不携带 final data；普通 callback、Record 或取消失败由\n * Product 转换为 `unavailable`，而不是抛出为 Run 的成功结果。\n */\nexport type CheckResult<\n  FinalData extends object = object,\n  Handoff extends object = never\n> = Readonly<\n  (\n    | ([Handoff] extends [never]\n        ? {\n            /** Check 已产生通过的 final data。 */\n            readonly status: \"passed\";\n            /** 此 Check 的主要终态事实。 */\n            readonly data: FinalData;\n          } & HandoffForbidden\n        : {\n            /** Check 已产生通过的 final data。 */\n            readonly status: \"passed\";\n            /** 此 Check 的主要终态事实。 */\n            readonly data: FinalData;\n            /** 仅由声明 `handoff: true` 的 provider 交接给 direct dependents 的 reference。 */\n            readonly handoff: Handoff;\n          })\n    | ({\n        /** Check 已产生失败的 final data。 */\n        readonly status: \"failed\";\n        /** 此 Check 的主要终态事实。 */\n        readonly data: FinalData;\n      } & HandoffForbidden)\n    | ({\n        /** Check 在当前 invocation 中不适用。 */\n        readonly status: \"not-applicable\";\n        /** 不适用的可选受控原因。 */\n        readonly reason?: CheckNotApplicableReason;\n      } & HandoffForbidden)\n    | ({\n        /** Check 不能提供 terminal data。 */\n        readonly status: \"unavailable\";\n        /** 不可用的受控原因。 */\n        readonly reason: CheckDeclaredUnavailableReason;\n      } & HandoffForbidden)\n  ) &\n    CheckResultMessages\n>;\n\n/** Check callback 的同步或异步 terminal result。 */\ntype CheckExecutionResult<FinalData extends object = object, Handoff extends object = never> =\n  | CheckResult<FinalData, Handoff>\n  | Promise<CheckResult<FinalData, Handoff>>;\n\ndeclare const CHECK_HANDOFF_PROVIDER_BRAND: unique symbol;\n\n/**\n * A Check returned by `defineCheck({ handoff: true })`. The type-only brand lets\n * `dependencies.get(provider)` infer the reference returned by that provider.\n *\n * @internal This is used by public callback types but authors never construct it.\n */\nexport type CheckHandoffProvider<\n  Id extends string = string,\n  Handoff extends object = object\n> = Readonly<{\n  readonly checkId: Id;\n  readonly handoff: true;\n  readonly [CHECK_HANDOFF_PROVIDER_BRAND]: Handoff;\n}>;\n\n/** 已 materialize 到 Core snapshot 的 Check terminal outcome。 */\nexport type CheckOutcome = Readonly<\n  | {\n      /** 已 materialize 的通过 outcome。 */\n      readonly status: \"passed\";\n      /** 已 canonicalize 的 primary final fact。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** 已 materialize 的失败 outcome。 */\n      readonly status: \"failed\";\n      /** 已 canonicalize 的 primary final fact。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** 已 materialize 的不适用 outcome。 */\n      readonly status: \"not-applicable\";\n      /** 不适用的可选受控原因。 */\n      readonly reason?: CheckNotApplicableReason;\n    }\n  | {\n      /** 已 materialize 的不可用 outcome。 */\n      readonly status: \"unavailable\";\n      /** 包含相关 upstream Check IDs 的受控原因。 */\n      readonly reason: CheckUnavailableReason;\n    }\n>;\n\n/** 递归只读 Check callback options，同时保留 array/tuple 形状和非 object leaf 类型。 */\nexport type DeepReadonly<Value> = Value extends readonly unknown[]\n  ? { readonly [Key in keyof Value]: DeepReadonly<Value[Key]> }\n  : Value extends object\n    ? { readonly [Key in keyof Value]: DeepReadonly<Value[Key]> }\n    : Value;\n\n/** callback 写入 supplemental Record 时的 Check-local identity。 */\ninterface RecordIdentityInput {\n  /** 在当前 Check 内唯一的 Record ID。 */\n  readonly id: string;\n}\n\n/** callback 写入 supplemental Records 的 Product-owned reporter。 */\ninterface CheckRecordReporter {\n  /** 记录一个补充事实；它不决定 Check 的 terminal status。 */\n  report(identity: RecordIdentityInput, data: object): void;\n}\n\n/** 读取已声明 direct relation final data 时的失败原因。 */\nexport type DependencyReadError = Readonly<\n  | {\n      /** 当前 Check 未声明所请求的 direct relation ID。 */\n      readonly code: \"dependency-not-declared\";\n      /** 被拒绝的 direct relation ID。 */\n      readonly checkId: string;\n    }\n  | {\n      /** 已声明 upstream 没有可读取的 final data。 */\n      readonly code: \"upstream-data-unavailable\";\n      /** 没有 final data 的 direct relation ID。 */\n      readonly checkId: string;\n      /** 阻止 readback 的 upstream terminal status。 */\n      readonly status: \"not-applicable\" | \"unavailable\";\n    }\n>;\n\n/** {@link CheckDependencies.get} 的受控 readback 结果。 */\nexport type DependencyReadResult = Readonly<\n  | {\n      /** 成功读取 direct relation final data。 */\n      readonly ok: true;\n      /** 被读取的 direct relation ID。 */\n      readonly checkId: string;\n      /** upstream 已结算为 `passed` 或 `failed` 的 status。 */\n      readonly status: \"passed\" | \"failed\";\n      /** 已与原对象脱离的上游依赖终态数据。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** direct relation data 不可读取。 */\n      readonly ok: false;\n      /** 失败的授权或 upstream-data reason。 */\n      readonly error: DependencyReadError;\n    }\n>;\n\n/** `dependsOn` provider-object handoff read 的受控结果。 */\nexport type DependencyHandoffReadResult<Id extends string, Handoff extends object> = Readonly<\n  | {\n      /** 同一 execution graph 中接受的 provider handoff。 */\n      readonly ok: true;\n      readonly checkId: Id;\n      readonly status: \"passed\";\n      /** Core-owned canonical provider final data。 */\n      readonly data: CanonicalJsonObject;\n      /** Provider 交接且未由 Product clone、freeze 或 serialize 的引用。 */\n      readonly handoff: Handoff;\n    }\n  | {\n      readonly ok: false;\n      readonly error: Readonly<\n        | {\n            /** 当前 Check 未将 provider 声明为 direct `dependsOn`。 */\n            readonly code: \"dependency-not-declared\";\n            readonly checkId: string;\n          }\n        | {\n            /** 已授权 provider 没有与其 Definition-internal identity 对应的已接受 passed handoff。 */\n            readonly code: \"upstream-handoff-unavailable\";\n            readonly checkId: string;\n          }\n      >;\n    }\n>;\n\n/** 当前 Check 的一个已规范化直接 relation 及其完整终态事实。 */\nexport type DependencyObservation = Readonly<{\n  /** 已规范化、稳定排序的 direct relation ID。 */\n  readonly checkId: string;\n  /** Core 已结算并冻结的四态 outcome。 */\n  readonly outcome: CheckOutcome;\n}>;\n\n/** 当前 Check 的已规范化直接 relation outcomes 的 data reader。 */\nexport interface CheckDependencies {\n  /**\n   * Reads a `handoff: true` provider's accepted invocation-private handoff.\n   *\n   * @returns Only an effective direct `dependsOn` provider declared with `handoff: true`, whose\n   * Definition-internal identity has accepted `passed` data, returns canonical data plus its typed\n   * reference. `observes`, string IDs, lookalikes and unavailable handoffs fail closed without\n   * upstream data.\n   */\n  get<Id extends string, Handoff extends object>(\n    provider: CheckHandoffProvider<Id, Handoff>\n  ): DependencyHandoffReadResult<Id, Handoff>;\n\n  /**\n   * 读取一个直接 relation 的 canonical final data。\n   *\n   * @returns 已声明的 `dependsOn` 或 `observes` relation 且为 `passed`/`failed` 的 Check 返回其 data；\n   * 未声明或没有 final data 时返回 `ok: false`，不会授权 transitive Check。\n   */\n  get(checkId: string): DependencyReadResult;\n\n  /**\n   * 枚举当前 Check 的全部已规范化 direct relation outcomes。\n   *\n   * @returns 按有效 direct relation ID 稳定排序、深度冻结的 `{ checkId, outcome }` observations；只含当前\n   * Check 显式或继承得到的 `dependsOn` / `observes` relation，不暴露 scheduler 历史、transitive 或未声明\n   * Check。\n   */\n  list(): readonly DependencyObservation[];\n}\n\n/**\n * Check callback 收到的 Product-owned execution context。\n *\n * @typeParam Options - 此 Check preparation 后传给 execution 的 options shape。\n */\nexport interface CheckExecutionContext<Options extends object> {\n  /** 当前 Check 的 absolute invocation artifact directory；caller 未授予时为 `null`。 */\n  readonly artifactDirectory: string | null;\n  /** 读取当前 Check 的已声明 direct relations。 */\n  readonly dependencies: CheckDependencies;\n  /** 同一次 invocation 内由 Product 统一提供的 identity。 */\n  readonly invocationId: string;\n  /** 深度只读、canonical 的 invocation-local prepared Check options。 */\n  readonly options: DeepReadonly<Options>;\n  /** 已规范化的项目根与 flags。 */\n  readonly project: CheckProjectContext;\n  /** 写入 supplemental Records 的 reporter。 */\n  readonly records: CheckRecordReporter;\n  /** 本次 invocation 的 cancellation signal。 */\n  readonly signal: AbortSignal;\n}\n\n/**\n * 一个 Check 的 callback signature。\n *\n * @typeParam Options - callback 从 context 读取的 prepared options shape。\n * @returns terminal Check result 或其 Promise。\n */\nexport type CheckExecution<Options extends object = object> = (\n  this: void,\n  context: CheckExecutionContext<Options>\n) => CheckExecutionResult;\n\n/**\n * 在 Check execution 前，可选地为本次 invocation 准备 options。\n *\n * @remarks `signal` 与同一次 callback execution 使用同一个 cancellation signal；`project` 与 execution\n * 收到同一个冻结 project context。实现应在可等待工作中协作退出，而不是留下悬挂 work。bivariant callback\n * 保持具体 options Check 可进入普通递归 Check collection；Product 仍只会用该 Check 自己的 authored options 调用它。精确结果见\n * {@link CheckPreparationResult}。\n */\nexport type CheckPreparation<\n  AuthoredOptions extends object = object,\n  PreparedOptions extends object = AuthoredOptions\n> = {\n  bivarianceHack(\n    this: void,\n    options: DeepReadonly<AuthoredOptions>,\n    signal: AbortSignal,\n    project?: CheckProjectContext\n  ): CheckPreparationResult<PreparedOptions> | Promise<CheckPreparationResult<PreparedOptions>>;\n}[\"bivarianceHack\"];\n\n/**\n * Check-owned preparation 的判别结果。\n *\n * `failure/block` 不允许 fallback，直接以 owning reason 结算为 unavailable；`failure/continue` 必须给出\n * fallback 并继续 execution。两种进入 execution 的值都只属于本次 invocation，Product canonicalize/freeze\n * 后传递，不会改写 Definition 中 authored options。两个 failure 分支都必须给出 reason；continue reason\n * 是 Check-owned diagnostic identity，当前不会单独 materialize 为 outcome，调用方通过 messages 与后续\n * outcome 观察结果；block 物理上不含 fallback 字段。\n */\nexport type CheckPreparationResult<PreparedOptions extends object = object> = Readonly<\n  | {\n      readonly status: \"success\";\n      readonly preparedOptions: PreparedOptions;\n      readonly messages?: readonly CheckMessage[];\n    }\n  | {\n      readonly status: \"failure\";\n      readonly action: \"block\";\n      readonly reason: CheckDeclaredUnavailableReason;\n      readonly messages?: readonly CheckMessage[];\n    }\n  | {\n      readonly status: \"failure\";\n      readonly action: \"continue\";\n      readonly fallback: PreparedOptions;\n      readonly reason: CheckReason;\n      readonly messages?: readonly CheckMessage[];\n    }\n>;\n\n/**\n * 普通递归 Check authoring value 的共享字段。\n *\n * @typeParam AuthoredOptions - Definition 中的 declarative options shape。\n * @typeParam PreparedOptions - preparation 后 callback 接收的 invocation-local options shape。\n * @remarks 该值可以同时有 `execute` 和 `checks`；只有 executable node 产生 final Check fact。\n */\ninterface CheckBase<AuthoredOptions extends object, _PreparedOptions extends object> {\n  /** 在 Definition 内唯一的 stable Check ID。 */\n  readonly checkId: string;\n  /** 人读 progress 与 output 使用的非空名称。 */\n  readonly displayName: string;\n  /** Check-owned declarative options；默认 Check 的嵌套 branch 以普通对象组合替换。 */\n  readonly options?: AuthoredOptions;\n  /** 仅当多 flag presence predicate 匹配时启用 executable Check；省略时始终启用。 */\n  readonly enabledByFlags?: CheckFlagEnablement;\n  /** `true` declares an invocation-private handoff on this executable Check. */\n  readonly handoff?: true;\n  /** 继承 scheduling context 的 child Checks，不会单独形成 container result。 */\n  readonly checks?: readonly Check[];\n  /** 必须全部 `passed` 才能开始当前 Check author work 的直接 prerequisite Check IDs。 */\n  readonly dependsOn?: InheritableCheckCollection<string>;\n  /** 等待任意 terminal outcome 并授权当前 Check readback 的直接 observation Check IDs。 */\n  readonly observes?: InheritableCheckCollection<string>;\n  /** 此 Check 及其 descendants 的最大并行预算。 */\n  readonly maxParallel?: number;\n  /** 同一 ready admission 层级中的静态优先级；省略时继承并最终规范化为 `0`。 */\n  readonly admissionPriority?: number;\n  /** 共享资源名称，或对父 mutex collection 的显式 edit。 */\n  readonly mutex?: InheritableCheckCollection<string>;\n  /** 静态 named resource claims；省略时继承，显式 mapping 完整替换。 */\n  readonly resourceClaims?: CheckResourceClaims;\n}\n\ninterface ExecutableCheckFields<\n  PreparedOptions extends object,\n  ExecutionResult = CheckExecutionResult\n> {\n  /** 可执行节点的 callback；拥有本字段的节点产生一个 terminal Check fact。 */\n  execute(this: void, context: CheckExecutionContext<PreparedOptions>): ExecutionResult;\n  /**\n   * `true` 时，progress renderer 不保留没有 accepted Record 或 message 的 passed row；运行中与所有保留的\n   * 终态 row 都无编号。该 policy 只属于 executable Check，不继承给 child Checks。\n   */\n  readonly omitQuietPassedRow?: true;\n}\n\n/** Container 只承载 children 与 scheduling，不能执行或设置 executable presentation policy。 */\ntype ContainerCheckFields = Readonly<{ execute?: never; omitQuietPassedRow?: never }>;\n\n/**\n * 判断两个 options shape 是否互相可赋值；互相可赋值时 execution 不需要 preparation 转换。\n */\ntype HasSameOptionsShape<AuthoredOptions extends object, PreparedOptions extends object> = [\n  AuthoredOptions\n] extends [PreparedOptions]\n  ? [PreparedOptions] extends [AuthoredOptions]\n    ? true\n    : false\n  : false;\n\n/** Prepared shape 不同时，preparation 是建立安全转换的必填边界。 */\ntype CheckPreparationField<AuthoredOptions extends object, PreparedOptions extends object> =\n  HasSameOptionsShape<AuthoredOptions, PreparedOptions> extends true\n    ? Readonly<{ readonly prepare?: CheckPreparation<AuthoredOptions, PreparedOptions> }>\n    : Readonly<{ readonly prepare: CheckPreparation<AuthoredOptions, PreparedOptions> }>;\n\n/**\n * Project Definition 中的普通递归 Check authoring value。\n *\n * @typeParam AuthoredOptions - Definition 中的 declarative options shape。\n * @typeParam PreparedOptions - preparation 后 callback 接收的 invocation-local options shape。\n * @remarks Definition 只闭合 authored JSON options；每个 admitted Check 先在自身 Task lifecycle 内执行\n * preparation，随后才执行 callback。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preparation；同形时可以\n * 省略。它不进入 declarative fingerprint 或 machine output。\n */\nexport type Check<\n  AuthoredOptions extends object = object,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckBase<AuthoredOptions, PreparedOptions> &\n  CheckPreparationField<AuthoredOptions, PreparedOptions> &\n  (\n    | ExecutableCheckFields<\n        PreparedOptions,\n        CheckExecutionResult | CheckExecutionResult<Readonly<Record<never, never>>, object>\n      >\n    | ContainerCheckFields\n  );\n\nexport type EmptyCheckOptions = Readonly<Record<never, never>>;\n\n/**\n * 防止宽泛的 parser 标注擦除 `PromiseLike`。canonical `then` field 可以保存 JSON data，\n * 但不能保存使该值成为 thenable 的 callable。\n */\ntype NonThenableData = Readonly<{ readonly then?: CanonicalJsonValue }>;\n\n/**\n * 将 canonical direct-relation data 还原为 provider final-data shape 的同步 parser。\n *\n * @typeParam FinalData - provider 在 `passed`/`failed` result 中声明的 final-data shape。\n * @remarks Product 不调用此 parser；provider 负责不受信任或跨版本 data 的业务验证。\n */\nexport type CheckDataParser<FinalData extends object = object> = (\n  this: void,\n  data: CanonicalJsonObject\n) => FinalData & NonThenableData;\n\ntype CheckAuthoringBase<\n  Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object\n> = Omit<CheckBase<AuthoredOptions, PreparedOptions>, \"checkId\" | \"handoff\" | \"options\"> &\n  CheckPreparationField<AuthoredOptions, PreparedOptions> &\n  Readonly<{ readonly checkId: Id }>;\n\n/** Ordinary Check branches cannot declare typed-provider parsing or private handoff. */\ntype OrdinaryCheckRestrictions = HandoffForbidden & Readonly<{ parseData?: undefined }>;\n\ntype OrdinaryCheckFields<PreparedOptions extends object> =\n  | (ExecutableCheckFields<PreparedOptions> & OrdinaryCheckRestrictions)\n  | (ContainerCheckFields & OrdinaryCheckRestrictions);\n\nexport type CheckWithOptions<\n  Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n  OrdinaryCheckFields<PreparedOptions> &\n  Readonly<{\n    readonly options: AuthoredOptions;\n  }>;\n\nexport type CheckWithoutOptions<Id extends string> = CheckAuthoringBase<\n  Id,\n  EmptyCheckOptions,\n  EmptyCheckOptions\n> &\n  OrdinaryCheckFields<EmptyCheckOptions> &\n  Readonly<{\n    readonly options?: never;\n  }>;\n\ninterface TypedCheckFields<\n  PreparedOptions extends object,\n  Parser extends CheckDataParser\n> extends ExecutableCheckFields<\n  PreparedOptions,\n  CheckExecutionResult<NoInfer<ReturnType<Parser>>>\n> {\n  /**\n   * 将 canonical runtime data 还原为 provider data。\n   *\n   * 启发式边界：同版本且受信任的 provider 若由测试保证 data shape，可仅将它实现为\n   * identity/type anchor。这不验证 JavaScript 或基于 cast 的 producer、历史或跨版本 artifact，\n   * 也不验证不受信任输入。\n   */\n  readonly parseData: Parser;\n\n  readonly handoff?: never;\n}\n\ninterface HandoffCheckFields<\n  PreparedOptions extends object,\n  Handoff extends object\n> extends ExecutableCheckFields<PreparedOptions, CheckExecutionResult<object, Handoff>> {\n  readonly handoff: true;\n  readonly parseData?: undefined;\n}\n\ninterface TypedHandoffCheckFields<\n  PreparedOptions extends object,\n  Parser extends CheckDataParser,\n  Handoff extends object\n> extends ExecutableCheckFields<\n  PreparedOptions,\n  CheckExecutionResult<NoInfer<ReturnType<Parser>>, Handoff>\n> {\n  readonly handoff: true;\n  readonly parseData: Parser;\n}\n\n/** Extracts the private reference type from an already-validated passed terminal result. */\ntype HandoffFromTerminalResult<Result> =\n  Extract<Awaited<Result>, { readonly status: \"passed\" }> extends {\n    readonly handoff: infer Handoff;\n  }\n    ? Handoff extends object\n      ? Handoff\n      : never\n    : never;\n\ntype PassedHandoffResult<Result> = Extract<Awaited<Result>, { readonly status: \"passed\" }>;\n\n/** Every passed branch must accept the complete inferred handoff type, not just one union member. */\ntype PassedHandoffBranchIsConsistent<Passed, Handoff> = Passed extends {\n  readonly handoff: infer BranchHandoff;\n}\n  ? [Handoff] extends [BranchHandoff]\n    ? true\n    : false\n  : false;\n\ntype HandoffTerminalResultConstraint<Result> =\n  false extends PassedHandoffBranchIsConsistent<\n    PassedHandoffResult<Result>,\n    HandoffFromTerminalResult<Result>\n  >\n    ? never\n    : unknown;\n\ntype HandoffExecution<PreparedOptions extends object, FinalData extends object = object> = (\n  this: void,\n  context: CheckExecutionContext<PreparedOptions>\n) => CheckExecutionResult<FinalData, object>;\n\nexport type TypedCheckWithOptions<\n  Id extends string,\n  AuthoredOptions extends object,\n  Parser extends CheckDataParser,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n  TypedCheckFields<PreparedOptions, Parser> &\n  Readonly<{\n    readonly options: AuthoredOptions;\n  }>;\n\nexport type TypedCheckWithoutOptions<\n  Id extends string,\n  Parser extends CheckDataParser\n> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> &\n  TypedCheckFields<EmptyCheckOptions, Parser> &\n  Readonly<{\n    readonly options?: never;\n  }>;\n\nexport type HandoffCheckWithOptions<\n  Id extends string,\n  AuthoredOptions extends object,\n  Handoff extends object,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n  HandoffCheckFields<PreparedOptions, Handoff> &\n  Readonly<{ readonly options: AuthoredOptions }>;\n\nexport type HandoffCheckWithoutOptions<\n  Id extends string,\n  Handoff extends object\n> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> &\n  HandoffCheckFields<EmptyCheckOptions, Handoff> &\n  Readonly<{ readonly options?: never }>;\n\nexport type TypedHandoffCheckWithOptions<\n  Id extends string,\n  AuthoredOptions extends object,\n  Parser extends CheckDataParser,\n  Handoff extends object,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n  TypedHandoffCheckFields<PreparedOptions, Parser, Handoff> &\n  Readonly<{ readonly options: AuthoredOptions }>;\n\nexport type TypedHandoffCheckWithoutOptions<\n  Id extends string,\n  Parser extends CheckDataParser,\n  Handoff extends object\n> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> &\n  TypedHandoffCheckFields<EmptyCheckOptions, Parser, Handoff> &\n  Readonly<{ readonly options?: never }>;\n\n/**\n * 定义一个 Check，同时保留 literal `checkId`、options 与 typed-provider parser 的 inference。\n *\n * @remarks 此函数负责 authoring inference；{@link run} 负责 Project Definition validation。\n * @example 定义带 options、Records 与 messages 的自定义 Check\n * ```ts\n * import { defineCheck, defineConfig, run } from \"@zxyycom/vibe-check\";\n *\n * function hasValidLicensePolicyOptions(options: object): boolean {\n *   const denied: unknown = Reflect.get(options, \"denied\");\n *   return (\n *     Object.keys(options).length === 1 &&\n *     Object.hasOwn(options, \"denied\") &&\n *     Array.isArray(denied) &&\n *     denied.every((license) => typeof license === \"string\")\n *   );\n * }\n *\n * const licensePolicy = defineCheck({\n *   checkId: \"license-policy\",\n *   displayName: \"License policy\",\n *   options: { denied: [\"GPL-3.0-only\"] },\n *   prepare(options) {\n *     return hasValidLicensePolicyOptions(options)\n *       ? { status: \"success\", preparedOptions: options }\n *       : { status: \"failure\", action: \"block\", reason: { code: \"invalid-options\" } };\n *   },\n *   omitQuietPassedRow: true,\n *   execute({ options, records, signal }) {\n *     if (signal.aborted) return { status: \"unavailable\", reason: { code: \"cancelled\" } };\n *\n *     const deniedCount = options.denied.length;\n *     if (deniedCount > 0) {\n *       records.report({ id: \"denied-license\" }, { count: deniedCount });\n *       return {\n *         status: \"failed\",\n *         data: { deniedCount },\n *         messages: [{ level: \"warning\", code: \"denied-license\", message: \"Denied licenses found.\" }]\n *       };\n *     }\n *     return { status: \"passed\", data: { deniedCount: 0 } };\n *   }\n * });\n * ```\n */\nexport function defineCheck<\n  const Id extends string,\n  AuthoredOptions extends object,\n  const Execution extends HandoffExecution<PreparedOptions>,\n  PreparedOptions extends object = AuthoredOptions\n>(\n  value: CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n    Readonly<{\n      readonly handoff: true;\n      readonly options: AuthoredOptions;\n      readonly parseData?: undefined;\n      readonly execute: Execution;\n    }> &\n    HandoffTerminalResultConstraint<ReturnType<Execution>>\n): HandoffCheckWithOptions<\n  Id,\n  AuthoredOptions,\n  HandoffFromTerminalResult<ReturnType<Execution>>,\n  PreparedOptions\n> &\n  CheckHandoffProvider<Id, HandoffFromTerminalResult<ReturnType<Execution>>>;\nexport function defineCheck<\n  const Id extends string,\n  const Execution extends HandoffExecution<EmptyCheckOptions>\n>(\n  value: CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> &\n    Readonly<{\n      readonly handoff: true;\n      readonly options?: never;\n      readonly parseData?: undefined;\n      readonly execute: Execution;\n    }> &\n    HandoffTerminalResultConstraint<ReturnType<Execution>>\n): HandoffCheckWithoutOptions<Id, HandoffFromTerminalResult<ReturnType<Execution>>> &\n  CheckHandoffProvider<Id, HandoffFromTerminalResult<ReturnType<Execution>>>;\nexport function defineCheck<\n  const Id extends string,\n  AuthoredOptions extends object,\n  const Parser extends CheckDataParser,\n  const Execution extends HandoffExecution<PreparedOptions, NoInfer<ReturnType<Parser>>>,\n  PreparedOptions extends object = AuthoredOptions\n>(\n  value: CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n    Readonly<{\n      readonly handoff: true;\n      readonly options: AuthoredOptions;\n      readonly parseData: Parser;\n      readonly execute: Execution;\n    }> &\n    HandoffTerminalResultConstraint<ReturnType<Execution>>\n): TypedHandoffCheckWithOptions<\n  Id,\n  AuthoredOptions,\n  Parser,\n  HandoffFromTerminalResult<ReturnType<Execution>>,\n  PreparedOptions\n> &\n  CheckHandoffProvider<Id, HandoffFromTerminalResult<ReturnType<Execution>>>;\nexport function defineCheck<\n  const Id extends string,\n  const Parser extends CheckDataParser,\n  const Execution extends HandoffExecution<EmptyCheckOptions, NoInfer<ReturnType<Parser>>>\n>(\n  value: CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> &\n    Readonly<{\n      readonly handoff: true;\n      readonly options?: never;\n      readonly parseData: Parser;\n      readonly execute: Execution;\n    }> &\n    HandoffTerminalResultConstraint<ReturnType<Execution>>\n): TypedHandoffCheckWithoutOptions<Id, Parser, HandoffFromTerminalResult<ReturnType<Execution>>> &\n  CheckHandoffProvider<Id, HandoffFromTerminalResult<ReturnType<Execution>>>;\nexport function defineCheck<\n  const Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object = AuthoredOptions\n>(\n  value: CheckWithOptions<Id, AuthoredOptions, PreparedOptions>\n): CheckWithOptions<Id, AuthoredOptions, PreparedOptions>;\nexport function defineCheck<const Id extends string>(\n  value: CheckWithoutOptions<Id>\n): CheckWithoutOptions<Id>;\nexport function defineCheck<\n  const Id extends string,\n  AuthoredOptions extends object,\n  const Parser extends CheckDataParser,\n  PreparedOptions extends object = AuthoredOptions\n>(\n  value: TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>\n): TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>;\nexport function defineCheck<const Id extends string, const Parser extends CheckDataParser>(\n  value: TypedCheckWithoutOptions<Id, Parser>\n): TypedCheckWithoutOptions<Id, Parser>;\nexport function defineCheck(value: Check): Check {\n  if (value.handoff === true) {\n    registerHandoffProviderIdentity(value);\n  }\n  return value;\n}\n"]}

package/dist/esm/check/flag-enablement.mjs

@@ -0,0 +1,32 @@
+/** 构造 `all` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function all(...conditions) {
+    return conditionSet("all", conditions);
+}
+/** 构造 `any` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function any(...conditions) {
+    return conditionSet("any", conditions);
+}
+/** 构造 `none` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function none(...conditions) {
+    return conditionSet("none", conditions);
+}
+/** 构造 `not-all` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function notAll(...conditions) {
+    return conditionSet("not-all", conditions);
+}
+/** 构造 `exactly-one` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function exactlyOne(...conditions) {
+    return conditionSet("exactly-one", conditions);
+}
+/** 构造 `not` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export function not(condition) {
+    return { condition, kind: "not" };
+}
+/** 为一个已声明的 project change ID 生成保留 flag token。 */
+export function changeFlag(id) {
+    return `vibe-check:change:${id}`;
+}
+function conditionSet(kind, conditions) {
+    return { kind, conditions };
+}
+//# sourceMappingURL=flag-enablement.mjs.map

package/dist/esm/check/flag-enablement.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag-enablement.mjs","sourceRoot":"","sources":["../../../src/check/flag-enablement.ts"],"names":[],"mappings":"AAuBA,+DAA+D;AAC/D,MAAM,UAAU,GAAG,CAAC,GAAG,UAAkC;IACvD,OAAO,YAAY,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AACzC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,GAAG,CAAC,GAAG,UAAkC;IACvD,OAAO,YAAY,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AACzC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,IAAI,CAAC,GAAG,UAAkC;IACxD,OAAO,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC1C,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,MAAM,CAAC,GAAG,UAAkC;IAC1D,OAAO,YAAY,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,UAAU,CACxB,GAAG,UAAkC;IAErC,OAAO,YAAY,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;AACjD,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,GAAG,CAAC,SAA6B;IAC/C,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACpC,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,UAAU,CAA0B,EAAM;IACxD,OAAO,qBAAqB,EAAE,EAAE,CAAC;AACnC,CAAC;AAED,SAAS,YAAY,CACnB,IAAU,EACV,UAAkC;IAElC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9B,CAAC","sourcesContent":["/** 一个递归 flag presence 条件表达式。字符串是唯一 leaf；operator 保留 author child 顺序和 multiplicity。 */\nexport type CheckFlagCondition =\n  | string\n  | Readonly<{\n      readonly kind: \"all\" | \"any\" | \"none\" | \"not-all\" | \"exactly-one\";\n      readonly conditions: readonly [CheckFlagCondition, ...CheckFlagCondition[]];\n    }>\n  | Readonly<{\n      readonly kind: \"not\";\n      readonly condition: CheckFlagCondition;\n    }>;\n\ntype CheckFlagConditionSetKind = \"all\" | \"any\" | \"none\" | \"not-all\" | \"exactly-one\";\ntype NonEmptyFlagConditions = readonly [CheckFlagCondition, ...CheckFlagCondition[]];\ntype CheckFlagConditionSet<Kind extends CheckFlagConditionSetKind> = Readonly<{\n  readonly kind: Kind;\n  readonly conditions: NonEmptyFlagConditions;\n}>;\ntype CheckFlagNegation = Readonly<{\n  readonly kind: \"not\";\n  readonly condition: CheckFlagCondition;\n}>;\n\n/** 构造 `all` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */\nexport function all(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<\"all\"> {\n  return conditionSet(\"all\", conditions);\n}\n\n/** 构造 `any` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */\nexport function any(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<\"any\"> {\n  return conditionSet(\"any\", conditions);\n}\n\n/** 构造 `none` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */\nexport function none(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<\"none\"> {\n  return conditionSet(\"none\", conditions);\n}\n\n/** 构造 `not-all` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */\nexport function notAll(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<\"not-all\"> {\n  return conditionSet(\"not-all\", conditions);\n}\n\n/** 构造 `exactly-one` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */\nexport function exactlyOne(\n  ...conditions: NonEmptyFlagConditions\n): CheckFlagConditionSet<\"exactly-one\"> {\n  return conditionSet(\"exactly-one\", conditions);\n}\n\n/** 构造 `not` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */\nexport function not(condition: CheckFlagCondition): CheckFlagNegation {\n  return { condition, kind: \"not\" };\n}\n\n/** 为一个已声明的 project change ID 生成保留 flag token。 */\nexport function changeFlag<const Id extends string>(id: Id): `vibe-check:change:${Id}` {\n  return `vibe-check:change:${id}`;\n}\n\nfunction conditionSet<Kind extends CheckFlagConditionSetKind>(\n  kind: Kind,\n  conditions: NonEmptyFlagConditions\n): CheckFlagConditionSet<Kind> {\n  return { kind, conditions };\n}\n\n/** executable Check 的 flag 选择控制。 */\nexport interface CheckFlagEnablement {\n  readonly when: CheckFlagCondition;\n  /**\n   * 条件命中时是否启动本 Check 的传递 `dependsOn` prerequisite；省略时只选择直接命中 Check。\n   * `observes` 不参与此选择，且 dependency 自己的 flag 条件不会阻止已启动 prerequisite。\n   */\n  readonly propagateDependsOn?: true;\n}\n"]}

package/dist/esm/check/handoff-provider-identity.mjs

@@ -0,0 +1,18 @@
+const handoffProviderIdentities = new WeakMap();
+class HandoffProviderIdentityValue {
+}
+/** Registers the identity that makes a `handoff: true` Check authentic to this package runtime. */
+export function registerHandoffProviderIdentity(value) {
+    handoffProviderIdentities.set(value, Object.freeze(new HandoffProviderIdentityValue()));
+}
+/** Returns the same-package identity registered by `defineCheck`. */
+export function getDefinedHandoffProviderIdentity(value) {
+    return typeof value === "object" && value !== null
+        ? handoffProviderIdentities.get(value)
+        : undefined;
+}
+/** Preserves a Definition-validated provider identity during materialization. */
+export function bindHandoffProviderIdentity(value, identity) {
+    handoffProviderIdentities.set(value, identity);
+}
+//# sourceMappingURL=handoff-provider-identity.mjs.map

package/dist/esm/check/handoff-provider-identity.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-provider-identity.mjs","sourceRoot":"","sources":["../../../src/check/handoff-provider-identity.ts"],"names":[],"mappings":"AAOA,MAAM,yBAAyB,GAAG,IAAI,OAAO,EAAmC,CAAC;AAEjF,MAAM,4BAA4B;CAEjC;AAED,mGAAmG;AACnG,MAAM,UAAU,+BAA+B,CAAC,KAAa;IAC3D,yBAAyB,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,4BAA4B,EAAE,CAAC,CAAC,CAAC;AAC1F,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,iCAAiC,CAC/C,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAChD,CAAC,CAAC,yBAAyB,CAAC,GAAG,CAAC,KAAK,CAAC;QACtC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,2BAA2B,CACzC,KAAa,EACb,QAAiC;IAEjC,yBAAyB,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACjD,CAAC","sourcesContent":["declare const HANDOFF_PROVIDER_IDENTITY_BRAND: unique symbol;\n\n/** Opaque same-package identity retained only by Definition and invocation execution. */\nexport type HandoffProviderIdentity = Readonly<{\n  readonly [HANDOFF_PROVIDER_IDENTITY_BRAND]: true;\n}>;\n\nconst handoffProviderIdentities = new WeakMap<object, HandoffProviderIdentity>();\n\nclass HandoffProviderIdentityValue implements HandoffProviderIdentity {\n  declare readonly [HANDOFF_PROVIDER_IDENTITY_BRAND]: true;\n}\n\n/** Registers the identity that makes a `handoff: true` Check authentic to this package runtime. */\nexport function registerHandoffProviderIdentity(value: object): void {\n  handoffProviderIdentities.set(value, Object.freeze(new HandoffProviderIdentityValue()));\n}\n\n/** Returns the same-package identity registered by `defineCheck`. */\nexport function getDefinedHandoffProviderIdentity(\n  value: unknown\n): HandoffProviderIdentity | undefined {\n  return typeof value === \"object\" && value !== null\n    ? handoffProviderIdentities.get(value)\n    : undefined;\n}\n\n/** Preserves a Definition-validated provider identity during materialization. */\nexport function bindHandoffProviderIdentity(\n  value: object,\n  identity: HandoffProviderIdentity\n): void {\n  handoffProviderIdentities.set(value, identity);\n}\n"]}

package/dist/esm/check/inherited-collection.mjs

@@ -1,7 +1,7 @@
 const INHERITED_CHECK_COLLECTION = Symbol("vibe-check.inherited-check-collection");
 const inheritedCollections = new WeakSet();
 /**
- * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。
+ * 创建可用于 `dependsOn`、`observes` 或 `mutex` 的受信任继承编辑。
  *
  * @typeParam T - 要添加或移除的 collection item 类型。
  * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。
@@ -44,7 +44,7 @@ function snapshotInheritedCollectionEntry(snapshot, key, descriptor) {
     if (!isDataDescriptor(descriptor))
         return "invalid";
     if (key === INHERITED_CHECK_COLLECTION) {
-        return descriptor.enumerable || descriptor.value !== true ? "invalid" : "marker";
+        return descriptor.enumerable === true || descriptor.value !== true ? "invalid" : "marker";
     }
     if (typeof key !== "string" || descriptor.enumerable !== true)
         return "invalid";

package/dist/esm/check/inherited-collection.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"inherited-collection.mjs","sourceRoot":"","sources":["../../../src/check/inherited-collection.ts"],"names":[],"mappings":"AAAA,MAAM,0BAA0B,GAAkB,MAAM,CAAC,uCAAuC,CAAC,CAAC;AAyBlG,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAAE,CAAC;AAI3C;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAI,KAAqC;IAC9D,MAAM,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,0BAA0B,CAAC,EAAE,IAAa,EAAE,CAAC;IACzE,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,0BAA0B,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IACjF,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gCAAgC,CAC9C,KAAwC;IAExC,IAAI,CAAC;QACH,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACtD,MAAM,QAAQ,GAA4B,EAAE,CAAC;QAC7C,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,gCAAgC,CAC5C,QAAQ,EACR,GAAG,EACH,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAC5C,CAAC;YACF,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC1C,IAAI,KAAK,KAAK,QAAQ;gBAAE,SAAS,GAAG,IAAI,CAAC;QAC3C,CAAC;QACD,OAAO,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAa;IAC5C,MAAM,SAAS,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED,SAAS,gCAAgC,CACvC,QAAiC,EACjC,GAAgB,EAChB,UAA0C;IAE1C,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,IAAI,GAAG,KAAK,0BAA0B,EAAE,CAAC;QACvC,OAAO,UAAU,CAAC,UAAU,IAAI,UAAU,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;IACnF,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,UAAU,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAChF,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE;QACnC,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,IAAI;QAChB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CACvB,UAA0C;IAE1C,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,CAAC;AAClG,CAAC","sourcesContent":["const INHERITED_CHECK_COLLECTION: unique symbol = Symbol(\"vibe-check.inherited-check-collection\");\n\n/** 使用 {@link inherit} 对父 Check 的 string collection 做显式增删的输入。 */\nexport type InheritCheckCollectionInput<T> = Readonly<\n  | { readonly add: readonly T[]; readonly remove?: readonly T[] }\n  | { readonly add?: readonly T[]; readonly remove: readonly T[] }\n>;\n\n/**\n * 由 {@link inherit} 创建、带有不可伪造 marker 的 collection edit。\n *\n * @remarks Definition validation 不接受看起来相同的 plain object。\n */\nexport type InheritedCheckCollection<T> = InheritCheckCollectionInput<T> &\n  Readonly<{\n    readonly [INHERITED_CHECK_COLLECTION]: true;\n  }>;\n\n/**\n * 可以直接替换父 collection 的数组，或由 {@link inherit} 表示的显式 edit。\n *\n * @typeParam T - collection item 类型。\n */\nexport type InheritableCheckCollection<T> = readonly T[] | InheritedCheckCollection<T>;\n\nconst inheritedCollections = new WeakSet();\n\ntype InheritedCollectionEntry = \"data\" | \"invalid\" | \"marker\";\n\n/**\n * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。\n *\n * @typeParam T - 要添加或移除的 collection item 类型。\n * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。\n * @returns 只有此函数创建的值会被 Definition validation 识别为 inherited collection。\n */\nexport function inherit<T>(value: InheritCheckCollectionInput<T>): InheritedCheckCollection<T> {\n  const result = { ...value, [INHERITED_CHECK_COLLECTION]: true as const };\n  Object.defineProperty(result, INHERITED_CHECK_COLLECTION, { enumerable: false });\n  inheritedCollections.add(result);\n  return result;\n}\n\nexport function isInheritedCheckCollection(\n  value: unknown\n): value is InheritedCheckCollection<unknown> {\n  return typeof value === \"object\" && value !== null && inheritedCollections.has(value);\n}\n\n/** Copies the trusted marker while preserving the authoring data's closed shape. */\nexport function snapshotInheritedCheckCollection(\n  value: InheritedCheckCollection<unknown>\n): Readonly<Record<string, unknown>> | undefined {\n  try {\n    if (!hasPlainObjectPrototype(value)) return undefined;\n    const snapshot: Record<string, unknown> = {};\n    let hasMarker = false;\n    for (const key of Reflect.ownKeys(value)) {\n      const entry = snapshotInheritedCollectionEntry(\n        snapshot,\n        key,\n        Object.getOwnPropertyDescriptor(value, key)\n      );\n      if (entry === \"invalid\") return undefined;\n      if (entry === \"marker\") hasMarker = true;\n    }\n    return hasMarker ? Object.freeze(snapshot) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction hasPlainObjectPrototype(value: object): boolean {\n  const prototype: unknown = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\nfunction snapshotInheritedCollectionEntry(\n  snapshot: Record<string, unknown>,\n  key: PropertyKey,\n  descriptor: PropertyDescriptor | undefined\n): InheritedCollectionEntry {\n  if (!isDataDescriptor(descriptor)) return \"invalid\";\n  if (key === INHERITED_CHECK_COLLECTION) {\n    return descriptor.enumerable || descriptor.value !== true ? \"invalid\" : \"marker\";\n  }\n  if (typeof key !== \"string\" || descriptor.enumerable !== true) return \"invalid\";\n  Object.defineProperty(snapshot, key, {\n    configurable: true,\n    enumerable: true,\n    value: descriptor.value,\n    writable: true\n  });\n  return \"data\";\n}\n\nfunction isDataDescriptor(\n  descriptor: PropertyDescriptor | undefined\n): descriptor is PropertyDescriptor {\n  return descriptor !== undefined && descriptor.get === undefined && descriptor.set === undefined;\n}\n"]}
+{"version":3,"file":"inherited-collection.mjs","sourceRoot":"","sources":["../../../src/check/inherited-collection.ts"],"names":[],"mappings":"AAAA,MAAM,0BAA0B,GAAkB,MAAM,CAAC,uCAAuC,CAAC,CAAC;AAyBlG,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAAE,CAAC;AAI3C;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAI,KAAqC;IAC9D,MAAM,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,0BAA0B,CAAC,EAAE,IAAa,EAAE,CAAC;IACzE,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,0BAA0B,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IACjF,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gCAAgC,CAC9C,KAAwC;IAExC,IAAI,CAAC;QACH,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACtD,MAAM,QAAQ,GAA4B,EAAE,CAAC;QAC7C,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,gCAAgC,CAC5C,QAAQ,EACR,GAAG,EACH,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAC5C,CAAC;YACF,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC1C,IAAI,KAAK,KAAK,QAAQ;gBAAE,SAAS,GAAG,IAAI,CAAC;QAC3C,CAAC;QACD,OAAO,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAa;IAC5C,MAAM,SAAS,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED,SAAS,gCAAgC,CACvC,QAAiC,EACjC,GAAgB,EAChB,UAA0C;IAE1C,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,IAAI,GAAG,KAAK,0BAA0B,EAAE,CAAC;QACvC,OAAO,UAAU,CAAC,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC5F,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,UAAU,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAChF,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE;QACnC,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,IAAI;QAChB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CACvB,UAA0C;IAE1C,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,CAAC;AAClG,CAAC","sourcesContent":["const INHERITED_CHECK_COLLECTION: unique symbol = Symbol(\"vibe-check.inherited-check-collection\");\n\n/** 使用 {@link inherit} 对父 Check 的 string collection 做显式增删的输入。 */\nexport type InheritCheckCollectionInput<T> = Readonly<\n  | { readonly add: readonly T[]; readonly remove?: readonly T[] }\n  | { readonly add?: readonly T[]; readonly remove: readonly T[] }\n>;\n\n/**\n * 由 {@link inherit} 创建、带有不可伪造 marker 的 collection edit。\n *\n * @remarks Definition validation 不接受看起来相同的 plain object。\n */\nexport type InheritedCheckCollection<T> = InheritCheckCollectionInput<T> &\n  Readonly<{\n    readonly [INHERITED_CHECK_COLLECTION]: true;\n  }>;\n\n/**\n * 可以直接替换父 collection 的数组，或由 {@link inherit} 表示的显式 edit。\n *\n * @typeParam T - collection item 类型。\n */\nexport type InheritableCheckCollection<T> = readonly T[] | InheritedCheckCollection<T>;\n\nconst inheritedCollections = new WeakSet();\n\ntype InheritedCollectionEntry = \"data\" | \"invalid\" | \"marker\";\n\n/**\n * 创建可用于 `dependsOn`、`observes` 或 `mutex` 的受信任继承编辑。\n *\n * @typeParam T - 要添加或移除的 collection item 类型。\n * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。\n * @returns 只有此函数创建的值会被 Definition validation 识别为 inherited collection。\n */\nexport function inherit<T>(value: InheritCheckCollectionInput<T>): InheritedCheckCollection<T> {\n  const result = { ...value, [INHERITED_CHECK_COLLECTION]: true as const };\n  Object.defineProperty(result, INHERITED_CHECK_COLLECTION, { enumerable: false });\n  inheritedCollections.add(result);\n  return result;\n}\n\nexport function isInheritedCheckCollection(\n  value: unknown\n): value is InheritedCheckCollection<unknown> {\n  return typeof value === \"object\" && value !== null && inheritedCollections.has(value);\n}\n\n/** Copies the trusted marker while preserving the authoring data's closed shape. */\nexport function snapshotInheritedCheckCollection(\n  value: InheritedCheckCollection<unknown>\n): Readonly<Record<string, unknown>> | undefined {\n  try {\n    if (!hasPlainObjectPrototype(value)) return undefined;\n    const snapshot: Record<string, unknown> = {};\n    let hasMarker = false;\n    for (const key of Reflect.ownKeys(value)) {\n      const entry = snapshotInheritedCollectionEntry(\n        snapshot,\n        key,\n        Object.getOwnPropertyDescriptor(value, key)\n      );\n      if (entry === \"invalid\") return undefined;\n      if (entry === \"marker\") hasMarker = true;\n    }\n    return hasMarker ? Object.freeze(snapshot) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction hasPlainObjectPrototype(value: object): boolean {\n  const prototype: unknown = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\nfunction snapshotInheritedCollectionEntry(\n  snapshot: Record<string, unknown>,\n  key: PropertyKey,\n  descriptor: PropertyDescriptor | undefined\n): InheritedCollectionEntry {\n  if (!isDataDescriptor(descriptor)) return \"invalid\";\n  if (key === INHERITED_CHECK_COLLECTION) {\n    return descriptor.enumerable === true || descriptor.value !== true ? \"invalid\" : \"marker\";\n  }\n  if (typeof key !== \"string\" || descriptor.enumerable !== true) return \"invalid\";\n  Object.defineProperty(snapshot, key, {\n    configurable: true,\n    enumerable: true,\n    value: descriptor.value,\n    writable: true\n  });\n  return \"data\";\n}\n\nfunction isDataDescriptor(\n  descriptor: PropertyDescriptor | undefined\n): descriptor is PropertyDescriptor {\n  return descriptor !== undefined && descriptor.get === undefined && descriptor.set === undefined;\n}\n"]}

package/dist/esm/check/project-changes.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=project-changes.mjs.map

package/dist/esm/check/project-changes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-changes.mjs","sourceRoot":"","sources":["../../../src/check/project-changes.ts"],"names":[],"mappings":"","sourcesContent":["/** 已配置的 project change preparation 产生的 file-centric evidence。 */\nexport type ProjectChanges = Readonly<\n  | {\n      readonly ok: true;\n      readonly files: readonly Readonly<{\n        readonly path: string;\n        readonly flags: readonly string[];\n      }>[];\n    }\n  | {\n      readonly ok: false;\n      readonly reason: Readonly<{ readonly code: string }>;\n    }\n>;\n"]}

package/dist/esm/check/project-context.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=project-context.mjs.map

package/dist/esm/check/project-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-context.mjs","sourceRoot":"","sources":["../../../src/check/project-context.ts"],"names":[],"mappings":"","sourcesContent":["import type { ProjectChanges } from \"./project-changes.ts\";\n\n/** 每次 Run 共享、冻结的 caller project context。 */\nexport interface CheckProjectContext {\n  /** 本次 Run 使用的绝对项目根目录。 */\n  readonly root: string;\n  /** 已去重、排序的 invocation-effective flags（caller flags 与派生 change flags）。 */\n  readonly flags: readonly string[];\n  /** 只在当前 Project Definition 配置 change preparation 时存在。 */\n  readonly changes?: ProjectChanges;\n}\n"]}

package/dist/esm/check-settlement/fact-validation.mjs

@@ -1,9 +1,10 @@
 import { canonicalizeJsonObject } from "../data-boundary/canonical-data.mjs";
 import { validateCheckDescriptor } from "../check/descriptor-validation.mjs";
-import { snapshotClosedArray, snapshotClosedRecord } from "../data-boundary/closed-values.mjs";
+import { hasExactPlainRecordKeys, hasRequiredAndOptionalRecordKeys, snapshotClosedArray, snapshotClosedRecord } from "../data-boundary/closed-values.mjs";
+import { isClosedCheckReason } from "./reason-shape.mjs";
 export function validateCoreSnapshot(value) {
     const snapshot = snapshotClosedRecord(value);
-    if (snapshot === undefined || !hasExactKeys(snapshot, ["checks", "records"])) {
+    if (snapshot === undefined || !hasExactPlainRecordKeys(snapshot, ["checks", "records"])) {
         return invalid("$", "Core snapshot must contain only checks and records");
     }
     const checksInput = snapshotClosedArray(snapshot.checks);
@@ -42,7 +43,8 @@ function validateChecks(values) {
     let previousCheckId;
     for (const [index, value] of values.entries()) {
         const check = snapshotClosedRecord(value);
-        if (check === undefined || !hasExactKeys(check, ["checkId", "displayName", "outcome"])) {
+        if (check === undefined ||
+            !hasExactPlainRecordKeys(check, ["checkId", "displayName", "outcome"])) {
             return invalid(`$.checks[${index}]`, "Core Check must be closed");
         }
         const definition = validateCheckDescriptor({
@@ -95,7 +97,7 @@ function validateRecords(values, checks) {
 }
 function validateRecordRow(value, index, ownerIds) {
     const record = snapshotClosedRecord(value);
-    if (record === undefined || !hasExactKeys(record, ["checkId", "id", "data"]))
+    if (record === undefined || !hasExactPlainRecordKeys(record, ["checkId", "id", "data"]))
         return invalid(`$.records[${index}]`, "Core Record must be closed");
     if (typeof record.checkId !== "string" ||
         !ownerIds.has(record.checkId) ||
@@ -123,7 +125,7 @@ function validateOutcome(value, path) {
 }
 function validateFinalOutcome(outcome, path) {
     if (outcome.status === "passed" || outcome.status === "failed") {
-        if (!hasExactKeys(outcome, ["status", "data"]))
+        if (!hasExactPlainRecordKeys(outcome, ["status", "data"]))
             return invalid(path, "Final outcome is not closed");
         const data = canonicalizeJsonObject(outcome.data);
         return data === undefined
@@ -133,7 +135,10 @@ function validateFinalOutcome(outcome, path) {
     return invalid(`${path}.status`, "Unknown Check outcome status");
 }
 function validateNotApplicableOutcome(outcome, path) {
-    if (!hasOptionalKeys(outcome, ["status"], ["reason"]))
+    if (!hasRequiredAndOptionalRecordKeys(outcome, {
+        optional: ["reason"],
+        required: ["status"]
+    }))
         return invalid(path, "Not-applicable outcome is not closed");
     const reason = validateReason(outcome.reason, false);
     return reason === null
@@ -141,7 +146,7 @@ function validateNotApplicableOutcome(outcome, path) {
         : accepted(Object.freeze(reason === undefined ? { status: "not-applicable" } : { status: "not-applicable", reason }));
 }
 function validateUnavailableOutcome(outcome, path) {
-    if (!hasExactKeys(outcome, ["status", "reason"]))
+    if (!hasExactPlainRecordKeys(outcome, ["status", "reason"]))
         return invalid(path, "Unavailable outcome is not closed");
     const reason = validateReason(outcome.reason, true);
     return reason === null || reason === undefined
@@ -152,9 +157,12 @@ function validateReason(value, allowCheckIds) {
     if (value === undefined)
         return undefined;
     const reason = snapshotClosedRecord(value);
-    if (!isClosedReason(reason, allowCheckIds))
+    if (!isClosedCheckReason(reason, allowCheckIds))
         return null;
-    if (!hasOptionalKeys(reason, ["code"], allowCheckIds ? ["checkIds"] : []))
+    if (!hasRequiredAndOptionalRecordKeys(reason, {
+        optional: allowCheckIds ? ["checkIds"] : [],
+        required: ["code"]
+    }))
         return null;
     if (!Object.hasOwn(reason, "checkIds"))
         return Object.freeze({ code: reason.code });
@@ -163,12 +171,6 @@ function validateReason(value, allowCheckIds) {
         return null;
     return Object.freeze({ code: reason.code, checkIds: Object.freeze(normalizedCheckIds) });
 }
-function isClosedReason(value, allowCheckIds) {
-    return (value !== undefined &&
-        typeof value.code === "string" &&
-        value.code.length > 0 &&
-        hasOptionalKeys(value, ["code"], allowCheckIds ? ["checkIds"] : []));
-}
 function normalizedReasonCheckIds(value, allowCheckIds) {
     const checkIds = snapshotClosedArray(value);
     if (!allowCheckIds ||
@@ -184,14 +186,6 @@ function normalizedReasonCheckIds(value, allowCheckIds) {
     }
     return Object.freeze(normalizedCheckIds);
 }
-function hasExactKeys(value, keys) {
-    return (Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key)));
-}
-function hasOptionalKeys(value, required, optional) {
-    const supported = new Set([...required, ...optional]);
-    return (required.every((key) => Object.hasOwn(value, key)) &&
-        Object.keys(value).every((key) => supported.has(key)));
-}
 function accepted(value) {
     return Object.freeze({ ok: true, value });
 }