@zxyycom/vibe-check 0.0.2 → 0.0.3

package/README.md

@@ -16,7 +16,7 @@ npm 负责安装 package；应用代码和质量脚本的最低运行要求是 *
 
 ## 随包提供的 Check
 
-如果项目需要的是常见质量检查，可以先从以下函数开始，而不必自己实现 `execution`。除 `maintenanceReminders(entries)` 与 `secretDetection({ files })` 有必填输入外，其余函数都可以无参调用；每份指南都包含最小用法、options、默认值、结果和安全边界。
+如果项目需要的是常见质量检查，可以先从以下函数开始，而不必自己实现 `execute`。除 `maintenanceReminders(entries)` 与 `secretDetection({ files })` 有必填输入外，其余函数都可以无参调用；每份指南都包含最小用法、options、默认值、结果和安全边界。
 
 | 你想检查什么 | 使用的导出 | 额外环境准备 |
 | --- | --- | --- |
@@ -25,11 +25,39 @@ npm 负责安装 package；应用代码和质量脚本的最低运行要求是 *
 | 函数规模、复杂度、最大嵌套和参数数量 | [`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) | 无需另装分析器。 |
 
-`duplicateDetection`、`fileMetrics`、`functionMetrics` 和 `markdownLinkValidation` 默认把普通 Finding 作为 non-blocking 警告保留下来；需要让 Finding 直接使 Check 失败时，在对应 options 中设置 `findingPolicy: "blocking"`。文件选择、阈值、外部工具和具体结果字段以各 Check 指南为准。
+### 为随包 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 快速开始
 
@@ -43,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 = {
@@ -83,19 +111,21 @@ node quality.ts
 
 ## 运行、配置与读取结果
 
-`defineConfig(...)` 定义可复用的 Checks、options、依赖、scheduler 和默认 outputs；`run(definition, controls?)` 的第二个参数只设置本次根目录、flags、取消、产物与日志目标、output overrides 和显式 aggregation。Controls 不能替换 Check 或 scheduler；字段位置和覆盖规则见 [API 机制](./docs/api-mechanics.md#参数应该放在哪里)。
+`defineConfig(...)` 定义可复用的 Checks、options、依赖、scheduler 和默认 outputs；`run(definition, controls?)` 的第二个参数只设置本次根目录、flags、取消、产物与日志目标、output overrides 和可选的本地 aggregation 函数。Controls 不能替换 Check 或 scheduler；字段位置和覆盖规则见 [API 机制](./docs/api-mechanics.md#参数应该放在哪里)。
 
 默认最多并行运行四个 Check，显示进度并把 machine files 写入 `artifacts/vibe-check`；diagnostic logging 默认关闭。上例显式关闭 machine publication。配置方法见[输出指南](./docs/guides/run-outputs.md)与[调度指南](./docs/guides/scheduling.md)。
 
-先判断 `RunResult.kind`；对有 snapshot 的结果，再按 `checkId` 读取 `snapshot.checks[].outcome` 的 `passed`、`failed`、`not-applicable` 或 `unavailable`。`completed` 不代表质量通过：CI 应显式判断目标 outcomes，或配置并读取 [`checkAggregation`](./docs/api-mechanics.md#runcontrols-与-check-aggregation)，再决定退出码。
+先判断 `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) 中同步解释同一有效列表，再决定退出码。
 
 ## 按任务继续阅读
 
 只读当前任务需要的专题；精确 overload、泛型推断和字段 JSDoc 以安装包中的 `types/**.d.ts` 为准。
 
+- [从项目质量目标构建 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)：并发资源、准入策略与终态观察。
@@ -107,6 +137,7 @@ node quality.ts
 | --- | --- | --- |
 | 按一份完整 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) |

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;AAyhBnC,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/** Check Task 在 admission 到 settlement 期间持有的静态 named resource units。 */\nexport type CheckResourceClaims = Readonly<Record<string, number>>;\n\n/** 多 flag Check 启用条件使用的集合 predicate。 */\nexport type CheckFlagEnablementMode = \"all\" | \"any\" | \"none\" | \"not-all\";\n\n/** executable Check 的声明式多 flag 启用条件。 */\nexport interface CheckFlagEnablement {\n  /** 非空 flag token 集合；Definition 会去重并稳定排序。 */\n  readonly flags: readonly [string, ...string[]];\n  /** 对声明 token 与本次 Run flags 执行的 presence predicate。 */\n  readonly mode: CheckFlagEnablementMode;\n  /**\n   * 条件命中时是否启动本 Check 的传递 `dependsOn` prerequisite；省略时保持只选择直接命中 Check 的兼容行为。\n   * `observes` 不参与此选择，且 dependency 自己的 flag 条件不会阻止本次已启动的 prerequisite。\n   */\n  readonly propagateDependsOn?: true;\n}\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/** 读取已声明 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/** 当前 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   * 读取一个直接 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/** 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 的 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) => 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  /** 仅当多 flag presence predicate 匹配时启用 executable Check；省略时始终启用。 */\n  readonly enabledByFlags?: CheckFlagEnablement;\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  /** 必须全部 `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  /** 已结算 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；每个 admitted Check 先在自身 Task lifecycle 内执行\n * preflight，随后才执行 callback。`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 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\" | \"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 * 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 *   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

@@ -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`、`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 || 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/facts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"facts.mjs","sourceRoot":"","sources":["../../../src/check-settlement/facts.ts"],"names":[],"mappings":"","sourcesContent":["import type { CheckDescriptor } from \"../check/descriptor.ts\";\nimport type { CheckOutcome } from \"../check/check.ts\";\n\nexport type {\n  CanonicalJsonObject,\n  CanonicalJsonPrimitive,\n  CanonicalJsonValue\n} from \"../data-boundary/canonical-data.ts\";\nexport type { CheckDescriptor, CheckOutcome };\n\n/** A Core Check has exactly one terminal outcome and no execution bookkeeping. */\nexport interface CoreCheck extends CheckDescriptor {\n  readonly outcome: CheckOutcome;\n}\n\n/** A supplemental Record is owned by its structural `{ checkId, id }` identity. */\nexport interface CoreRecord {\n  readonly checkId: string;\n  readonly id: string;\n  readonly data: import(\"../data-boundary/canonical-data.ts\").CanonicalJsonObject;\n}\n\n/** The complete Product entity projection. Invocation metadata belongs to Run, not Core. */\nexport interface CoreSnapshot {\n  readonly checks: readonly CoreCheck[];\n  readonly records: readonly CoreRecord[];\n}\n"]}
+{"version":3,"file":"facts.mjs","sourceRoot":"","sources":["../../../src/check-settlement/facts.ts"],"names":[],"mappings":"","sourcesContent":["import type { CheckDescriptor } from \"../check/descriptor.ts\";\nimport type { CheckOutcome } from \"../check/check.ts\";\n\nexport type {\n  CanonicalJsonObject,\n  CanonicalJsonPrimitive,\n  CanonicalJsonValue\n} from \"../data-boundary/canonical-data.ts\";\nexport type { CheckDescriptor, CheckOutcome };\n\n/** Core Check 恰有一个 terminal outcome，不携带 execution bookkeeping。 */\nexport interface CoreCheck extends CheckDescriptor {\n  readonly outcome: CheckOutcome;\n}\n\n/** A supplemental Record is owned by its structural `{ checkId, id }` identity. */\nexport interface CoreRecord {\n  readonly checkId: string;\n  readonly id: string;\n  readonly data: import(\"../data-boundary/canonical-data.ts\").CanonicalJsonObject;\n}\n\n/** The complete Product entity projection. Invocation metadata belongs to Run, not Core. */\nexport interface CoreSnapshot {\n  readonly checks: readonly CoreCheck[];\n  readonly records: readonly CoreRecord[];\n}\n"]}

package/dist/esm/check-settlement/record-store.mjs

@@ -10,7 +10,7 @@ export class CoreRecordStore {
         if (id === undefined || data === undefined)
             return this.#reject(slot, "record-invalid");
         let records = this.#recordsByCheckId.get(slot.checkId);
-        if (records?.has(id))
+        if (records?.has(id) === true)
             return this.#reject(slot, "record-conflict");
         if (records === undefined) {
             records = new Map();

package/dist/esm/check-settlement/record-store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"record-store.mjs","sourceRoot":"","sources":["../../../src/check-settlement/record-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { canonicalizeJsonObject } from \"../data-boundary/canonical-data.ts\";\nimport type { CoreRecord } from \"./facts.ts\";\nimport { snapshotClosedRecord } from \"../data-boundary/closed-values.ts\";\n\nexport type RecordSubmissionResult = \"committed\" | \"rejected\";\n\nconst EMPTY_RECORDS: readonly CoreRecord[] = Object.freeze([]);\nexport type RecordDiagnostic = \"record-conflict\" | \"record-invalid\";\n\nexport interface CoreRecordSlot {\n  readonly checkId: string;\n  readonly diagnostics: Set<RecordDiagnostic>;\n}\n\n/** Holds Check-local supplemental Records without inventing a composite string identity. */\nexport class CoreRecordStore {\n  readonly #recordsByCheckId = new Map<string, Map<string, CoreRecord>>();\n\n  public report(\n    slot: CoreRecordSlot,\n    rawIdentity: unknown,\n    rawData: unknown\n  ): RecordSubmissionResult {\n    const id = recordId(rawIdentity);\n    const data = canonicalizeJsonObject(rawData);\n    if (id === undefined || data === undefined) return this.#reject(slot, \"record-invalid\");\n\n    let records = this.#recordsByCheckId.get(slot.checkId);\n    if (records?.has(id)) return this.#reject(slot, \"record-conflict\");\n    if (records === undefined) {\n      records = new Map<string, CoreRecord>();\n      this.#recordsByCheckId.set(slot.checkId, records);\n    }\n    const record: CoreRecord = Object.freeze({ checkId: slot.checkId, id, data });\n    records.set(id, record);\n    return \"committed\";\n  }\n\n  public recordsForCheckInCanonicalOrder(checkId: string): readonly CoreRecord[] {\n    const recordsById = this.#recordsByCheckId.get(checkId);\n    if (recordsById === undefined) return EMPTY_RECORDS;\n    return Object.freeze(\n      [...recordsById.values()].sort((left, right) => compareText(left.id, right.id))\n    );\n  }\n\n  public recordsInCanonicalOrder(): readonly CoreRecord[] {\n    return Object.freeze(\n      [...this.#recordsByCheckId.keys()]\n        .sort(compareText)\n        .flatMap((checkId) => this.recordsForCheckInCanonicalOrder(checkId))\n    );\n  }\n\n  #reject(slot: CoreRecordSlot, diagnostic: RecordDiagnostic): \"rejected\" {\n    slot.diagnostics.add(diagnostic);\n    return \"rejected\";\n  }\n}\n\nfunction recordId(value: unknown): string | undefined {\n  const identity = snapshotClosedRecord(value);\n  return identity !== undefined &&\n    Object.keys(identity).length === 1 &&\n    Object.hasOwn(identity, \"id\") &&\n    typeof identity.id === \"string\" &&\n    identity.id.length > 0\n    ? identity.id\n    : undefined;\n}\n\nfunction compareText(left: string, right: string): number {\n  if (left < right) return -1;\n  if (left > right) return 1;\n  return 0;\n}\n"]}
+{"version":3,"file":"record-store.mjs","sourceRoot":"","sources":["../../../src/check-settlement/record-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { canonicalizeJsonObject } from \"../data-boundary/canonical-data.ts\";\nimport type { CoreRecord } from \"./facts.ts\";\nimport { snapshotClosedRecord } from \"../data-boundary/closed-values.ts\";\n\nexport type RecordSubmissionResult = \"committed\" | \"rejected\";\n\nconst EMPTY_RECORDS: readonly CoreRecord[] = Object.freeze([]);\nexport type RecordDiagnostic = \"record-conflict\" | \"record-invalid\";\n\nexport interface CoreRecordSlot {\n  readonly checkId: string;\n  readonly diagnostics: Set<RecordDiagnostic>;\n}\n\n/** Holds Check-local supplemental Records without inventing a composite string identity. */\nexport class CoreRecordStore {\n  readonly #recordsByCheckId = new Map<string, Map<string, CoreRecord>>();\n\n  public report(\n    slot: CoreRecordSlot,\n    rawIdentity: unknown,\n    rawData: unknown\n  ): RecordSubmissionResult {\n    const id = recordId(rawIdentity);\n    const data = canonicalizeJsonObject(rawData);\n    if (id === undefined || data === undefined) return this.#reject(slot, \"record-invalid\");\n\n    let records = this.#recordsByCheckId.get(slot.checkId);\n    if (records?.has(id) === true) return this.#reject(slot, \"record-conflict\");\n    if (records === undefined) {\n      records = new Map<string, CoreRecord>();\n      this.#recordsByCheckId.set(slot.checkId, records);\n    }\n    const record: CoreRecord = Object.freeze({ checkId: slot.checkId, id, data });\n    records.set(id, record);\n    return \"committed\";\n  }\n\n  public recordsForCheckInCanonicalOrder(checkId: string): readonly CoreRecord[] {\n    const recordsById = this.#recordsByCheckId.get(checkId);\n    if (recordsById === undefined) return EMPTY_RECORDS;\n    return Object.freeze(\n      [...recordsById.values()].sort((left, right) => compareText(left.id, right.id))\n    );\n  }\n\n  public recordsInCanonicalOrder(): readonly CoreRecord[] {\n    return Object.freeze(\n      [...this.#recordsByCheckId.keys()]\n        .sort(compareText)\n        .flatMap((checkId) => this.recordsForCheckInCanonicalOrder(checkId))\n    );\n  }\n\n  #reject(slot: CoreRecordSlot, diagnostic: RecordDiagnostic): \"rejected\" {\n    slot.diagnostics.add(diagnostic);\n    return \"rejected\";\n  }\n}\n\nfunction recordId(value: unknown): string | undefined {\n  const identity = snapshotClosedRecord(value);\n  return identity !== undefined &&\n    Object.keys(identity).length === 1 &&\n    Object.hasOwn(identity, \"id\") &&\n    typeof identity.id === \"string\" &&\n    identity.id.length > 0\n    ? identity.id\n    : undefined;\n}\n\nfunction compareText(left: string, right: string): number {\n  if (left < right) return -1;\n  if (left > right) return 1;\n  return 0;\n}\n"]}

package/dist/esm/data-boundary/canonical-data.mjs

@@ -1,17 +1,35 @@
 const encoder = new TextEncoder();
 /**
- * Materializes arbitrary author data without property reads or JSON hooks.
- * The returned graph is detached, prototype-safe, and deeply frozen before it
- * becomes a Core fact. Canonical text order is applied explicitly at serialization.
+ * 将输入规范化为独立且递归冻结的 canonical JSON 对象副本。
+ *
+ * 递归内容只接受普通对象或 null-prototype 对象、标准无空洞数组和有限 JSON 基本值；仅当顶层结果是
+ * 非数组对象时返回该副本。输出对象使用 null prototype，输出对象和数组均独立于输入且递归冻结。不调用
+ * getter 或 `toJSON`；无效输入、循环引用或反射失败返回 `undefined`。反射 Proxy 时仍可能执行其 trap，
+ * 不隔离 trap 的副作用。
  */
 export function canonicalizeJsonObject(value) {
     const canonical = canonicalize(value, new Set());
     return canonical !== undefined && isCanonicalJsonObject(canonical) ? canonical : undefined;
 }
+/**
+ * 将输入规范化为独立且递归冻结的 canonical JSON 值副本。
+ *
+ * 接受 `null`、boolean、string、有限 number、普通对象或 null-prototype 对象，以及标准无空洞数组；
+ * `-0` 转换为 `0`，输出对象使用 null prototype。拒绝存取器、稀疏数组、不可枚举的自有属性、非有限
+ * number 和其它 prototype。不调用 getter 或 `toJSON`；无效输入、循环引用或反射失败返回 `undefined`。
+ * 反射 Proxy 时仍可能执行其 trap，不隔离 trap 的副作用。`CanonicalJsonPrimitive` 的 `number` 在
+ * TypeScript 中仍可表示 `NaN`，有限性只能由本函数在运行时检查。
+ */
 export function canonicalizeJsonValue(value) {
     return canonicalize(value, new Set());
 }
-/** Serializes detached canonical JSON with explicit lexical object-key ordering. */
+/**
+ * 规范化输入后生成确定性的无额外空白 JSON 文本。
+ *
+ * 对象键按固定的 lexical `<` 顺序输出，不承诺遵循外部 canonical-JSON 标准。即使同一对象已经过
+ * 规范化，`JSON.stringify` 仍按 ECMAScript 的整数索引键顺序输出，不能替代本函数。输入规则与 Proxy
+ * 边界同 `canonicalizeJsonValue`；无效输入或无法反射的 Proxy 均抛出 `TypeError`。
+ */
 export function canonicalJsonText(value) {
     const canonical = canonicalizeJsonValue(value);
     if (canonical === undefined) {
@@ -19,7 +37,12 @@ export function canonicalJsonText(value) {
     }
     return canonicalText(canonical);
 }
-/** Emits canonical UTF-8 JSON without invoking author getters or `toJSON`. */
+/**
+ * 规范化输入后生成与 `canonicalJsonText` 相同的确定性 UTF-8 JSON 字节。
+ *
+ * 函数自行完成规范化与固定键排序，不要求调用方先取得 canonical JSON 值。输入规则、Proxy 边界和
+ * `TypeError` 失败方式与 `canonicalJsonText` 相同。
+ */
 export function canonicalJsonBytes(value) {
     return encoder.encode(canonicalJsonText(value));
 }
@@ -69,7 +92,7 @@ function denseCanonicalArrayLength(value) {
         return undefined;
     const keys = Reflect.ownKeys(value);
     const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
-    if (!isDataDescriptor(lengthDescriptor) || lengthDescriptor.enumerable)
+    if (!isDataDescriptor(lengthDescriptor) || lengthDescriptor.enumerable === true)
         return undefined;
     const length = lengthDescriptor.value;
     if (typeof length !== "number" ||
@@ -143,7 +166,13 @@ function canonicalText(value) {
     }
     return `{${Object.keys(value)
         .sort(compareText)
-        .map((key) => `${JSON.stringify(key)}:${canonicalText(value[key])}`)
+        .map((key) => {
+        const entry = value[key];
+        if (entry === undefined) {
+            throw new TypeError(`Canonical JSON object is missing declared key: ${key}`);
+        }
+        return `${JSON.stringify(key)}:${canonicalText(entry)}`;
+    })
         .join(",")}}`;
 }
 function isCanonicalJsonArray(value) {

package/dist/esm/data-boundary/canonical-data.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"canonical-data.mjs","sourceRoot":"","sources":["../../../src/data-boundary/canonical-data.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CanonicalJsonObject, CanonicalJsonValue } from \"./canonical-json.ts\";\n\nexport type {\n  CanonicalJsonObject,\n  CanonicalJsonPrimitive,\n  CanonicalJsonValue\n} from \"./canonical-json.ts\";\n\nconst encoder = new TextEncoder();\n\n/**\n * Materializes arbitrary author data without property reads or JSON hooks.\n * The returned graph is detached, prototype-safe, and deeply frozen before it\n * becomes a Core fact. Canonical text order is applied explicitly at serialization.\n */\nexport function canonicalizeJsonObject(value: unknown): CanonicalJsonObject | undefined {\n  const canonical = canonicalize(value, new Set<object>());\n  return canonical !== undefined && isCanonicalJsonObject(canonical) ? canonical : undefined;\n}\n\nexport function canonicalizeJsonValue(value: unknown): CanonicalJsonValue | undefined {\n  return canonicalize(value, new Set<object>());\n}\n\n/** Serializes detached canonical JSON with explicit lexical object-key ordering. */\nexport function canonicalJsonText(value: unknown): string {\n  const canonical = canonicalizeJsonValue(value);\n  if (canonical === undefined) {\n    throw new TypeError(\"Canonical JSON could not safely materialize the input\");\n  }\n  return canonicalText(canonical);\n}\n\n/** Emits canonical UTF-8 JSON without invoking author getters or `toJSON`. */\nexport function canonicalJsonBytes(value: unknown): Uint8Array {\n  return encoder.encode(canonicalJsonText(value));\n}\n\nfunction canonicalize(value: unknown, ancestors: Set<object>): CanonicalJsonValue | undefined {\n  if (value === null) return null;\n  const primitive = canonicalPrimitive(value);\n  if (primitive !== undefined) return primitive;\n  if (typeof value !== \"object\") return undefined;\n  if (!admitCanonicalObject(value, ancestors)) return undefined;\n\n  try {\n    return Array.isArray(value)\n      ? canonicalizeArray(value, ancestors)\n      : canonicalizeObject(value, ancestors);\n  } catch {\n    return undefined;\n  } finally {\n    ancestors.delete(value);\n  }\n}\n\nfunction canonicalPrimitive(value: unknown): CanonicalJsonValue | undefined {\n  if (typeof value === \"boolean\" || typeof value === \"string\") return value;\n  if (typeof value !== \"number\" || !Number.isFinite(value)) return undefined;\n  return Object.is(value, -0) ? 0 : value;\n}\n\nfunction admitCanonicalObject(value: object, ancestors: Set<object>): boolean {\n  if (ancestors.has(value)) return false;\n  ancestors.add(value);\n  return true;\n}\n\nfunction canonicalizeArray(\n  value: readonly unknown[],\n  ancestors: Set<object>\n): readonly CanonicalJsonValue[] | undefined {\n  const length = denseCanonicalArrayLength(value);\n  if (length === undefined) return undefined;\n  return canonicalArrayElements(value, length, ancestors);\n}\n\nfunction denseCanonicalArrayLength(value: readonly unknown[]): number | undefined {\n  if (Object.getPrototypeOf(value) !== Array.prototype) return undefined;\n  const keys = Reflect.ownKeys(value);\n  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, \"length\");\n  if (!isDataDescriptor(lengthDescriptor) || lengthDescriptor.enumerable) return undefined;\n  const length = lengthDescriptor.value;\n  if (\n    typeof length !== \"number\" ||\n    !Number.isSafeInteger(length) ||\n    length < 0 ||\n    keys.length !== length + 1\n  )\n    return undefined;\n  if (!keys.includes(\"length\")) return undefined;\n  return length;\n}\n\nfunction canonicalArrayElements(\n  value: readonly unknown[],\n  length: number,\n  ancestors: Set<object>\n): readonly CanonicalJsonValue[] | undefined {\n  const values: CanonicalJsonValue[] = [];\n  for (let index = 0; index < length; index += 1) {\n    const key = String(index);\n    const descriptor = Object.getOwnPropertyDescriptor(value, key);\n    if (!isEnumerableDataDescriptor(descriptor)) return undefined;\n    const item = canonicalize(descriptor.value, ancestors);\n    if (item === undefined) return undefined;\n    values.push(item);\n  }\n  return Object.freeze(values);\n}\n\nfunction canonicalizeObject(\n  value: object,\n  ancestors: Set<object>\n): CanonicalJsonObject | undefined {\n  const prototype: unknown = Object.getPrototypeOf(value);\n  if (prototype !== Object.prototype && prototype !== null) return undefined;\n  const keys: string[] = [];\n  for (const key of Reflect.ownKeys(value)) {\n    if (typeof key !== \"string\") return undefined;\n    keys.push(key);\n  }\n\n  const snapshot: Record<string, CanonicalJsonValue> = {};\n  Object.setPrototypeOf(snapshot, null);\n  for (const key of keys.sort(compareText)) {\n    const descriptor = Object.getOwnPropertyDescriptor(value, key);\n    if (!isEnumerableDataDescriptor(descriptor)) return undefined;\n    const item = canonicalize(descriptor.value, ancestors);\n    if (item === undefined) return undefined;\n    Object.defineProperty(snapshot, key, {\n      configurable: false,\n      enumerable: true,\n      value: item,\n      writable: false\n    });\n  }\n  return Object.freeze(snapshot);\n}\n\ntype DataDescriptor = Omit<PropertyDescriptor, \"get\" | \"set\" | \"value\"> &\n  Readonly<{\n    get?: undefined;\n    set?: undefined;\n    value: unknown;\n  }>;\n\nfunction isDataDescriptor(\n  descriptor: PropertyDescriptor | undefined\n): descriptor is DataDescriptor {\n  return (\n    descriptor !== undefined &&\n    descriptor.get === undefined &&\n    descriptor.set === undefined &&\n    Object.hasOwn(descriptor, \"value\")\n  );\n}\n\nfunction isEnumerableDataDescriptor(\n  descriptor: PropertyDescriptor | undefined\n): descriptor is DataDescriptor {\n  return isDataDescriptor(descriptor) && descriptor.enumerable === true;\n}\n\nfunction isCanonicalJsonObject(value: CanonicalJsonValue): value is CanonicalJsonObject {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction canonicalText(value: CanonicalJsonValue): string {\n  if (value === null || typeof value !== \"object\") return JSON.stringify(value);\n  if (isCanonicalJsonArray(value)) {\n    return `[${value.map((entry) => canonicalText(entry)).join(\",\")}]`;\n  }\n  return `{${Object.keys(value)\n    .sort(compareText)\n    .map((key) => `${JSON.stringify(key)}:${canonicalText(value[key])}`)\n    .join(\",\")}}`;\n}\n\nfunction isCanonicalJsonArray(value: CanonicalJsonValue): value is readonly CanonicalJsonValue[] {\n  return Array.isArray(value);\n}\n\nfunction compareText(left: string, right: string): number {\n  if (left < right) return -1;\n  if (left > right) return 1;\n  return 0;\n}\n"]}
+{"version":3,"file":"canonical-data.mjs","sourceRoot":"","sources":["../../../src/data-boundary/canonical-data.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,EAAE,IAAI,GAAG,EAAU,CAAC,CAAC;IACzD,OAAO,SAAS,KAAK,SAAS,IAAI,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7F,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,GAAG,EAAU,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,SAAS,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,SAAS,CAAC,uDAAuD,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,aAAa,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,YAAY,CAAC,KAAc,EAAE,SAAsB;IAC1D,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IAE9D,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACzB,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC;YACrC,CAAC,CAAC,kBAAkB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3E,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC1C,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa,EAAE,SAAsB;IACjE,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,iBAAiB,CACxB,KAAyB,EACzB,SAAsB;IAEtB,MAAM,MAAM,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAChD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAyB;IAC1D,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACvE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,gBAAgB,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC1E,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAClG,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC;IACtC,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC;QAC7B,MAAM,GAAG,CAAC;QACV,IAAI,CAAC,MAAM,KAAK,MAAM,GAAG,CAAC;QAE1B,OAAO,SAAS,CAAC;IACnB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,sBAAsB,CAC7B,KAAyB,EACzB,MAAc,EACd,SAAsB;IAEtB,MAAM,MAAM,GAAyB,EAAE,CAAC;IACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/D,IAAI,CAAC,0BAA0B,CAAC,UAAU,CAAC;YAAE,OAAO,SAAS,CAAC;QAC9D,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACvD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,kBAAkB,CACzB,KAAa,EACb,SAAsB;IAEtB,MAAM,SAAS,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxD,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC3E,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IAED,MAAM,QAAQ,GAAuC,EAAE,CAAC;IACxD,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACzC,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/D,IAAI,CAAC,0BAA0B,CAAC,UAAU,CAAC;YAAE,OAAO,SAAS,CAAC;QAC9D,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACvD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE;YACnC,YAAY,EAAE,KAAK;YACnB,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,IAAI;YACX,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC;AAOD,SAAS,gBAAgB,CACvB,UAA0C;IAE1C,OAAO,CACL,UAAU,KAAK,SAAS;QACxB,UAAU,CAAC,GAAG,KAAK,SAAS;QAC5B,UAAU,CAAC,GAAG,KAAK,SAAS;QAC5B,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CACnC,CAAC;AACJ,CAAC;AAED,SAAS,0BAA0B,CACjC,UAA0C;IAE1C,OAAO,gBAAgB,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,KAAK,IAAI,CAAC;AACxE,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAyB;IACtD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,aAAa,CAAC,KAAyB;IAC9C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;SAC1B,IAAI,CAAC,WAAW,CAAC;SACjB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACX,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,SAAS,CAAC,kDAAkD,GAAG,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1D,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAyB;IACrD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,KAAa;IAC9C,IAAI,IAAI,GAAG,KAAK;QAAE,OAAO,CAAC,CAAC,CAAC;IAC5B,IAAI,IAAI,GAAG,KAAK;QAAE,OAAO,CAAC,CAAC;IAC3B,OAAO,CAAC,CAAC;AACX,CAAC","sourcesContent":["import type { CanonicalJsonObject, CanonicalJsonValue } from \"./canonical-json.ts\";\n\nexport type {\n  CanonicalJsonObject,\n  CanonicalJsonPrimitive,\n  CanonicalJsonValue\n} from \"./canonical-json.ts\";\n\nconst encoder = new TextEncoder();\n\n/**\n * 将输入规范化为独立且递归冻结的 canonical JSON 对象副本。\n *\n * 递归内容只接受普通对象或 null-prototype 对象、标准无空洞数组和有限 JSON 基本值；仅当顶层结果是\n * 非数组对象时返回该副本。输出对象使用 null prototype，输出对象和数组均独立于输入且递归冻结。不调用\n * getter 或 `toJSON`；无效输入、循环引用或反射失败返回 `undefined`。反射 Proxy 时仍可能执行其 trap，\n * 不隔离 trap 的副作用。\n */\nexport function canonicalizeJsonObject(value: unknown): CanonicalJsonObject | undefined {\n  const canonical = canonicalize(value, new Set<object>());\n  return canonical !== undefined && isCanonicalJsonObject(canonical) ? canonical : undefined;\n}\n\n/**\n * 将输入规范化为独立且递归冻结的 canonical JSON 值副本。\n *\n * 接受 `null`、boolean、string、有限 number、普通对象或 null-prototype 对象，以及标准无空洞数组；\n * `-0` 转换为 `0`，输出对象使用 null prototype。拒绝存取器、稀疏数组、不可枚举的自有属性、非有限\n * number 和其它 prototype。不调用 getter 或 `toJSON`；无效输入、循环引用或反射失败返回 `undefined`。\n * 反射 Proxy 时仍可能执行其 trap，不隔离 trap 的副作用。`CanonicalJsonPrimitive` 的 `number` 在\n * TypeScript 中仍可表示 `NaN`，有限性只能由本函数在运行时检查。\n */\nexport function canonicalizeJsonValue(value: unknown): CanonicalJsonValue | undefined {\n  return canonicalize(value, new Set<object>());\n}\n\n/**\n * 规范化输入后生成确定性的无额外空白 JSON 文本。\n *\n * 对象键按固定的 lexical `<` 顺序输出，不承诺遵循外部 canonical-JSON 标准。即使同一对象已经过\n * 规范化，`JSON.stringify` 仍按 ECMAScript 的整数索引键顺序输出，不能替代本函数。输入规则与 Proxy\n * 边界同 `canonicalizeJsonValue`；无效输入或无法反射的 Proxy 均抛出 `TypeError`。\n */\nexport function canonicalJsonText(value: unknown): string {\n  const canonical = canonicalizeJsonValue(value);\n  if (canonical === undefined) {\n    throw new TypeError(\"Canonical JSON could not safely materialize the input\");\n  }\n  return canonicalText(canonical);\n}\n\n/**\n * 规范化输入后生成与 `canonicalJsonText` 相同的确定性 UTF-8 JSON 字节。\n *\n * 函数自行完成规范化与固定键排序，不要求调用方先取得 canonical JSON 值。输入规则、Proxy 边界和\n * `TypeError` 失败方式与 `canonicalJsonText` 相同。\n */\nexport function canonicalJsonBytes(value: unknown): Uint8Array {\n  return encoder.encode(canonicalJsonText(value));\n}\n\nfunction canonicalize(value: unknown, ancestors: Set<object>): CanonicalJsonValue | undefined {\n  if (value === null) return null;\n  const primitive = canonicalPrimitive(value);\n  if (primitive !== undefined) return primitive;\n  if (typeof value !== \"object\") return undefined;\n  if (!admitCanonicalObject(value, ancestors)) return undefined;\n\n  try {\n    return Array.isArray(value)\n      ? canonicalizeArray(value, ancestors)\n      : canonicalizeObject(value, ancestors);\n  } catch {\n    return undefined;\n  } finally {\n    ancestors.delete(value);\n  }\n}\n\nfunction canonicalPrimitive(value: unknown): CanonicalJsonValue | undefined {\n  if (typeof value === \"boolean\" || typeof value === \"string\") return value;\n  if (typeof value !== \"number\" || !Number.isFinite(value)) return undefined;\n  return Object.is(value, -0) ? 0 : value;\n}\n\nfunction admitCanonicalObject(value: object, ancestors: Set<object>): boolean {\n  if (ancestors.has(value)) return false;\n  ancestors.add(value);\n  return true;\n}\n\nfunction canonicalizeArray(\n  value: readonly unknown[],\n  ancestors: Set<object>\n): readonly CanonicalJsonValue[] | undefined {\n  const length = denseCanonicalArrayLength(value);\n  if (length === undefined) return undefined;\n  return canonicalArrayElements(value, length, ancestors);\n}\n\nfunction denseCanonicalArrayLength(value: readonly unknown[]): number | undefined {\n  if (Object.getPrototypeOf(value) !== Array.prototype) return undefined;\n  const keys = Reflect.ownKeys(value);\n  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, \"length\");\n  if (!isDataDescriptor(lengthDescriptor) || lengthDescriptor.enumerable === true) return undefined;\n  const length = lengthDescriptor.value;\n  if (\n    typeof length !== \"number\" ||\n    !Number.isSafeInteger(length) ||\n    length < 0 ||\n    keys.length !== length + 1\n  )\n    return undefined;\n  if (!keys.includes(\"length\")) return undefined;\n  return length;\n}\n\nfunction canonicalArrayElements(\n  value: readonly unknown[],\n  length: number,\n  ancestors: Set<object>\n): readonly CanonicalJsonValue[] | undefined {\n  const values: CanonicalJsonValue[] = [];\n  for (let index = 0; index < length; index += 1) {\n    const key = String(index);\n    const descriptor = Object.getOwnPropertyDescriptor(value, key);\n    if (!isEnumerableDataDescriptor(descriptor)) return undefined;\n    const item = canonicalize(descriptor.value, ancestors);\n    if (item === undefined) return undefined;\n    values.push(item);\n  }\n  return Object.freeze(values);\n}\n\nfunction canonicalizeObject(\n  value: object,\n  ancestors: Set<object>\n): CanonicalJsonObject | undefined {\n  const prototype: unknown = Object.getPrototypeOf(value);\n  if (prototype !== Object.prototype && prototype !== null) return undefined;\n  const keys: string[] = [];\n  for (const key of Reflect.ownKeys(value)) {\n    if (typeof key !== \"string\") return undefined;\n    keys.push(key);\n  }\n\n  const snapshot: Record<string, CanonicalJsonValue> = {};\n  Object.setPrototypeOf(snapshot, null);\n  for (const key of keys.sort(compareText)) {\n    const descriptor = Object.getOwnPropertyDescriptor(value, key);\n    if (!isEnumerableDataDescriptor(descriptor)) return undefined;\n    const item = canonicalize(descriptor.value, ancestors);\n    if (item === undefined) return undefined;\n    Object.defineProperty(snapshot, key, {\n      configurable: false,\n      enumerable: true,\n      value: item,\n      writable: false\n    });\n  }\n  return Object.freeze(snapshot);\n}\n\ntype DataDescriptor = Omit<PropertyDescriptor, \"get\" | \"set\" | \"value\"> &\n  Readonly<{\n    value: unknown;\n  }>;\n\nfunction isDataDescriptor(\n  descriptor: PropertyDescriptor | undefined\n): descriptor is DataDescriptor {\n  return (\n    descriptor !== undefined &&\n    descriptor.get === undefined &&\n    descriptor.set === undefined &&\n    Object.hasOwn(descriptor, \"value\")\n  );\n}\n\nfunction isEnumerableDataDescriptor(\n  descriptor: PropertyDescriptor | undefined\n): descriptor is DataDescriptor {\n  return isDataDescriptor(descriptor) && descriptor.enumerable === true;\n}\n\nfunction isCanonicalJsonObject(value: CanonicalJsonValue): value is CanonicalJsonObject {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction canonicalText(value: CanonicalJsonValue): string {\n  if (value === null || typeof value !== \"object\") return JSON.stringify(value);\n  if (isCanonicalJsonArray(value)) {\n    return `[${value.map((entry) => canonicalText(entry)).join(\",\")}]`;\n  }\n  return `{${Object.keys(value)\n    .sort(compareText)\n    .map((key) => {\n      const entry = value[key];\n      if (entry === undefined) {\n        throw new TypeError(`Canonical JSON object is missing declared key: ${key}`);\n      }\n      return `${JSON.stringify(key)}:${canonicalText(entry)}`;\n    })\n    .join(\",\")}}`;\n}\n\nfunction isCanonicalJsonArray(value: CanonicalJsonValue): value is readonly CanonicalJsonValue[] {\n  return Array.isArray(value);\n}\n\nfunction compareText(left: string, right: string): number {\n  if (left < right) return -1;\n  if (left > right) return 1;\n  return 0;\n}\n"]}

package/dist/esm/data-boundary/canonical-json.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"canonical-json.mjs","sourceRoot":"","sources":["../../../src/data-boundary/canonical-json.ts"],"names":[],"mappings":"","sourcesContent":["/** Package-private static shape for Product's detached canonical JSON facts. */\nexport type CanonicalJsonPrimitive = boolean | null | number | string;\n\nexport type CanonicalJsonValue =\n  | CanonicalJsonPrimitive\n  | readonly CanonicalJsonValue[]\n  | CanonicalJsonObject;\n\nexport interface CanonicalJsonObject {\n  readonly [key: string]: CanonicalJsonValue;\n}\n"]}
+{"version":3,"file":"canonical-json.mjs","sourceRoot":"","sources":["../../../src/data-boundary/canonical-json.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Canonical JSON 基本值的静态结构类型。\n *\n * TypeScript 的 `number` 无法在静态层区分有限值与 `NaN` / `Infinity`；因此此类型不能证明值已经由\n * canonical API 规范化。运行时只接受有限 number，并将 `-0` 转换为 `0`。\n */\nexport type CanonicalJsonPrimitive = boolean | null | number | string;\n\n/**\n * Canonical JSON 值的递归只读静态结构类型。\n *\n * 它描述基本值、数组和对象能够如何组合，便于声明参数和结果；不证明值已经通过 canonical API 的\n * 运行时规范化、递归冻结或循环检查。\n */\nexport type CanonicalJsonValue =\n  | CanonicalJsonPrimitive\n  | readonly CanonicalJsonValue[]\n  | CanonicalJsonObject;\n\n/**\n * Canonical JSON 对象的只读静态结构类型。\n *\n * 该类型不证明值来自 canonical API。API 实际返回的对象使用 null prototype，没有继承的对象方法；\n * 检查属性时使用 `Object.hasOwn`，不要调用 `value.hasOwnProperty`。\n */\nexport interface CanonicalJsonObject {\n  readonly [key: string]: CanonicalJsonValue;\n}\n"]}