@zxyycom/vibe-check 0.0.2 → 0.0.3

package/types/check/check.d.ts

@@ -1,5 +1,7 @@
 import type { CanonicalJsonObject, CanonicalJsonValue } from "../data-boundary/canonical-json.ts";
 import type { InheritableCheckCollection } from "./inherited-collection.ts";
+import type { CheckFlagEnablement } from "./flag-enablement.ts";
+import type { CheckProjectContext } from "./project-context.ts";
 export { inherit, isInheritedCheckCollection, snapshotInheritedCheckCollection } from "./inherited-collection.ts";
 export type { InheritCheckCollectionInput, InheritableCheckCollection, InheritedCheckCollection } from "./inherited-collection.ts";
 /** Check 无法给出 final data 时返回的受控 reason code。 */
@@ -32,26 +34,16 @@ export interface CheckMessage {
 /** 可附加到每个 {@link CheckResult} branch 的有序 terminal messages。 */
 export interface CheckResultMessages {
     /** 省略、`undefined` 或空数组都表示没有 supplemental messages。 */
-    readonly messages?: readonly CheckMessage[];
+    readonly messages?: readonly CheckMessage[] | undefined;
 }
-/** 已结算 Check 在人读 progress 中的可见性。 */
-export type CheckVisibility = "always" | "attention";
+type HandoffForbidden = Readonly<{
+    readonly handoff?: never;
+}>;
 /** Check Task 在 admission 到 settlement 期间持有的静态 named resource units。 */
 export type CheckResourceClaims = Readonly<Record<string, number>>;
-/** 多 flag Check 启用条件使用的集合 predicate。 */
-export type CheckFlagEnablementMode = "all" | "any" | "none" | "not-all";
-/** executable Check 的声明式多 flag 启用条件。 */
-export interface CheckFlagEnablement {
-    /** 非空 flag token 集合；Definition 会去重并稳定排序。 */
-    readonly flags: readonly [string, ...string[]];
-    /** 对声明 token 与本次 Run flags 执行的 presence predicate。 */
-    readonly mode: CheckFlagEnablementMode;
-    /**
-     * 条件命中时是否启动本 Check 的传递 `dependsOn` prerequisite；省略时保持只选择直接命中 Check 的兼容行为。
-     * `observes` 不参与此选择，且 dependency 自己的 flag 条件不会阻止本次已启动的 prerequisite。
-     */
-    readonly propagateDependsOn?: true;
-}
+export type { CheckFlagCondition, CheckFlagEnablement } from "./flag-enablement.ts";
+export type { ProjectChanges } from "./project-changes.ts";
+export type { CheckProjectContext } from "./project-context.ts";
 /**
  * Check callback 的 terminal result。
  *
@@ -59,27 +51,48 @@ export interface CheckFlagEnablement {
  * @remarks `not-applicable` 与 `unavailable` 不携带 final data；普通 callback、Record 或取消失败由
  * Product 转换为 `unavailable`，而不是抛出为 Run 的成功结果。
  */
-export type CheckResult<FinalData extends object = object> = Readonly<({
+export type CheckResult<FinalData extends object = object, Handoff extends object = never> = Readonly<(([Handoff] extends [never] ? {
     /** Check 已产生通过的 final data。 */
     readonly status: "passed";
     /** 此 Check 的主要终态事实。 */
     readonly data: FinalData;
-} | {
+} & HandoffForbidden : {
+    /** Check 已产生通过的 final data。 */
+    readonly status: "passed";
+    /** 此 Check 的主要终态事实。 */
+    readonly data: FinalData;
+    /** 仅由声明 `handoff: true` 的 provider 交接给 direct dependents 的 reference。 */
+    readonly handoff: Handoff;
+}) | ({
     /** Check 已产生失败的 final data。 */
     readonly status: "failed";
     /** 此 Check 的主要终态事实。 */
     readonly data: FinalData;
-} | {
+} & HandoffForbidden) | ({
     /** Check 在当前 invocation 中不适用。 */
     readonly status: "not-applicable";
     /** 不适用的可选受控原因。 */
     readonly reason?: CheckNotApplicableReason;
-} | {
+} & HandoffForbidden) | ({
     /** Check 不能提供 terminal data。 */
     readonly status: "unavailable";
     /** 不可用的受控原因。 */
     readonly reason: CheckDeclaredUnavailableReason;
-}) & CheckResultMessages>;
+} & HandoffForbidden)) & CheckResultMessages>;
+/** Check callback 的同步或异步 terminal result。 */
+type CheckExecutionResult<FinalData extends object = object, Handoff extends object = never> = CheckResult<FinalData, Handoff> | Promise<CheckResult<FinalData, Handoff>>;
+declare const CHECK_HANDOFF_PROVIDER_BRAND: unique symbol;
+/**
+ * A Check returned by `defineCheck({ handoff: true })`. The type-only brand lets
+ * `dependencies.get(provider)` infer the reference returned by that provider.
+ *
+ * @internal This is used by public callback types but authors never construct it.
+ */
+export type CheckHandoffProvider<Id extends string = string, Handoff extends object = object> = Readonly<{
+    readonly checkId: Id;
+    readonly handoff: true;
+    readonly [CHECK_HANDOFF_PROVIDER_BRAND]: Handoff;
+}>;
 /** 已 materialize 到 Core snapshot 的 Check terminal outcome。 */
 export type CheckOutcome = Readonly<{
     /** 已 materialize 的通过 outcome。 */
@@ -102,10 +115,12 @@ export type CheckOutcome = Readonly<{
     /** 包含相关 upstream Check IDs 的受控原因。 */
     readonly reason: CheckUnavailableReason;
 }>;
-/** 将 callback options 转为不可变观察值的递归 utility type。 */
-export type DeepReadonly<T> = T extends string | number | boolean | null ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? {
-    readonly [Key in keyof T]: DeepReadonly<T[Key]>;
-} : never;
+/** 递归只读 Check callback options，同时保留 array/tuple 形状和非 object leaf 类型。 */
+export type DeepReadonly<Value> = Value extends readonly unknown[] ? {
+    readonly [Key in keyof Value]: DeepReadonly<Value[Key]>;
+} : Value extends object ? {
+    readonly [Key in keyof Value]: DeepReadonly<Value[Key]>;
+} : Value;
 /** callback 写入 supplemental Record 时的 Check-local identity。 */
 interface RecordIdentityInput {
     /** 在当前 Check 内唯一的 Record ID。 */
@@ -146,6 +161,28 @@ export type DependencyReadResult = Readonly<{
     /** 失败的授权或 upstream-data reason。 */
     readonly error: DependencyReadError;
 }>;
+/** `dependsOn` provider-object handoff read 的受控结果。 */
+export type DependencyHandoffReadResult<Id extends string, Handoff extends object> = Readonly<{
+    /** 同一 execution graph 中接受的 provider handoff。 */
+    readonly ok: true;
+    readonly checkId: Id;
+    readonly status: "passed";
+    /** Core-owned canonical provider final data。 */
+    readonly data: CanonicalJsonObject;
+    /** Provider 交接且未由 Product clone、freeze 或 serialize 的引用。 */
+    readonly handoff: Handoff;
+} | {
+    readonly ok: false;
+    readonly error: Readonly<{
+        /** 当前 Check 未将 provider 声明为 direct `dependsOn`。 */
+        readonly code: "dependency-not-declared";
+        readonly checkId: string;
+    } | {
+        /** 已授权 provider 没有与其 Definition-internal identity 对应的已接受 passed handoff。 */
+        readonly code: "upstream-handoff-unavailable";
+        readonly checkId: string;
+    }>;
+}>;
 /** 当前 Check 的一个已规范化直接 relation 及其完整终态事实。 */
 export type DependencyObservation = Readonly<{
     /** 已规范化、稳定排序的 direct relation ID。 */
@@ -155,6 +192,15 @@ export type DependencyObservation = Readonly<{
 }>;
 /** 当前 Check 的已规范化直接 relation outcomes 的 data reader。 */
 export interface CheckDependencies {
+    /**
+     * Reads a `handoff: true` provider's accepted invocation-private handoff.
+     *
+     * @returns Only an effective direct `dependsOn` provider declared with `handoff: true`, whose
+     * Definition-internal identity has accepted `passed` data, returns canonical data plus its typed
+     * reference. `observes`, string IDs, lookalikes and unavailable handoffs fail closed without
+     * upstream data.
+     */
+    get<Id extends string, Handoff extends object>(provider: CheckHandoffProvider<Id, Handoff>): DependencyHandoffReadResult<Id, Handoff>;
     /**
      * 读取一个直接 relation 的 canonical final data。
      *
@@ -171,17 +217,10 @@ export interface CheckDependencies {
      */
     list(): readonly DependencyObservation[];
 }
-/** callback 可读取的、由 Product 规范化的项目上下文。 */
-export interface CheckProjectContext {
-    /** 本次 Run 使用的绝对项目根目录。 */
-    readonly root: string;
-    /** 已去重、排序的 caller-supplied flags。 */
-    readonly flags: readonly string[];
-}
 /**
  * Check callback 收到的 Product-owned execution context。
  *
- * @typeParam Options - 此 Check preflight 后传给 execution 的 options shape。
+ * @typeParam Options - 此 Check preparation 后传给 execution 的 options shape。
  */
 export interface CheckExecutionContext<Options extends object> {
     /** 当前 Check 的 absolute invocation artifact directory；caller 未授予时为 `null`。 */
@@ -205,20 +244,20 @@ export interface CheckExecutionContext<Options extends object> {
  * @typeParam Options - callback 从 context 读取的 prepared options shape。
  * @returns terminal Check result 或其 Promise。
  */
-export type CheckExecution<Options extends object = object> = (this: void, context: CheckExecutionContext<Options>) => CheckResult | Promise<CheckResult>;
+export type CheckExecution<Options extends object = object> = (this: void, context: CheckExecutionContext<Options>) => CheckExecutionResult;
 /**
  * 在 Check execution 前，可选地为本次 invocation 准备 options。
  *
- * @remarks `signal` 与同一次 callback execution 使用同一个 cancellation signal；实现应在可等待工作中
- * 协作退出，而不是留下悬挂 work。bivariant callback 保持具体 options Check 可进入普通递归 Check
- * collection；Product 仍只会用该 Check 自己的 authored options 调用它。精确结果见
- * {@link CheckPreflightResult}。
+ * @remarks `signal` 与同一次 callback execution 使用同一个 cancellation signal；`project` 与 execution
+ * 收到同一个冻结 project context。实现应在可等待工作中协作退出，而不是留下悬挂 work。bivariant callback
+ * 保持具体 options Check 可进入普通递归 Check collection；Product 仍只会用该 Check 自己的 authored options 调用它。精确结果见
+ * {@link CheckPreparationResult}。
  */
-export type CheckPreflight<AuthoredOptions extends object = object, PreparedOptions extends object = AuthoredOptions> = {
-    bivarianceHack(this: void, options: DeepReadonly<AuthoredOptions>, signal: AbortSignal): CheckPreflightResult<PreparedOptions> | Promise<CheckPreflightResult<PreparedOptions>>;
+export type CheckPreparation<AuthoredOptions extends object = object, PreparedOptions extends object = AuthoredOptions> = {
+    bivarianceHack(this: void, options: DeepReadonly<AuthoredOptions>, signal: AbortSignal, project?: CheckProjectContext): CheckPreparationResult<PreparedOptions> | Promise<CheckPreparationResult<PreparedOptions>>;
 }["bivarianceHack"];
 /**
- * Check-owned preflight 的判别结果。
+ * Check-owned preparation 的判别结果。
  *
  * `failure/block` 不允许 fallback，直接以 owning reason 结算为 unavailable；`failure/continue` 必须给出
  * fallback 并继续 execution。两种进入 execution 的值都只属于本次 invocation，Product canonicalize/freeze
@@ -226,7 +265,7 @@ export type CheckPreflight<AuthoredOptions extends object = object, PreparedOpti
  * 是 Check-owned diagnostic identity，当前不会单独 materialize 为 outcome，调用方通过 messages 与后续
  * outcome 观察结果；block 物理上不含 fallback 字段。
  */
-export type CheckPreflightResult<PreparedOptions extends object = object> = Readonly<{
+export type CheckPreparationResult<PreparedOptions extends object = object> = Readonly<{
     readonly status: "success";
     readonly preparedOptions: PreparedOptions;
     readonly messages?: readonly CheckMessage[];
@@ -246,10 +285,10 @@ export type CheckPreflightResult<PreparedOptions extends object = object> = Read
  * 普通递归 Check authoring value 的共享字段。
  *
  * @typeParam AuthoredOptions - Definition 中的 declarative options shape。
- * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。
- * @remarks 该值可以同时有 `execution` 和 `checks`；只有 executable node 产生 final Check fact。
+ * @typeParam PreparedOptions - preparation 后 callback 接收的 invocation-local options shape。
+ * @remarks 该值可以同时有 `execute` 和 `checks`；只有 executable node 产生 final Check fact。
  */
-interface CheckBase<AuthoredOptions extends object, PreparedOptions extends object> {
+interface CheckBase<AuthoredOptions extends object, _PreparedOptions extends object> {
     /** 在 Definition 内唯一的 stable Check ID。 */
     readonly checkId: string;
     /** 人读 progress 与 output 使用的非空名称。 */
@@ -258,8 +297,8 @@ interface CheckBase<AuthoredOptions extends object, PreparedOptions extends obje
     readonly options?: AuthoredOptions;
     /** 仅当多 flag presence predicate 匹配时启用 executable Check；省略时始终启用。 */
     readonly enabledByFlags?: CheckFlagEnablement;
-    /** 可执行节点的 callback；省略时此节点只承载递归 children。 */
-    execution?(this: void, context: CheckExecutionContext<PreparedOptions>): CheckResult | Promise<CheckResult>;
+    /** `true` declares an invocation-private handoff on this executable Check. */
+    readonly handoff?: true;
     /** 继承 scheduling context 的 child Checks，不会单独形成 container result。 */
     readonly checks?: readonly Check[];
     /** 必须全部 `passed` 才能开始当前 Check author work 的直接 prerequisite Check IDs。 */
@@ -274,31 +313,43 @@ interface CheckBase<AuthoredOptions extends object, PreparedOptions extends obje
     readonly mutex?: InheritableCheckCollection<string>;
     /** 静态 named resource claims；省略时继承，显式 mapping 完整替换。 */
     readonly resourceClaims?: CheckResourceClaims;
-    /** 已结算 Check 的人读可见性；可执行节点默认 `always`。 */
-    readonly visibility?: CheckVisibility;
 }
+interface ExecutableCheckFields<PreparedOptions extends object, ExecutionResult = CheckExecutionResult> {
+    /** 可执行节点的 callback；拥有本字段的节点产生一个 terminal Check fact。 */
+    execute(this: void, context: CheckExecutionContext<PreparedOptions>): ExecutionResult;
+    /**
+     * `true` 时，progress renderer 不保留没有 accepted Record 或 message 的 passed row；运行中与所有保留的
+     * 终态 row 都无编号。该 policy 只属于 executable Check，不继承给 child Checks。
+     */
+    readonly omitQuietPassedRow?: true;
+}
+/** Container 只承载 children 与 scheduling，不能执行或设置 executable presentation policy。 */
+type ContainerCheckFields = Readonly<{
+    execute?: never;
+    omitQuietPassedRow?: never;
+}>;
 /**
  * 判断两个 options shape 是否互相可赋值；互相可赋值时 execution 不需要 preparation 转换。
  */
 type HasSameOptionsShape<AuthoredOptions extends object, PreparedOptions extends object> = [
     AuthoredOptions
 ] extends [PreparedOptions] ? [PreparedOptions] extends [AuthoredOptions] ? true : false : false;
-/** Prepared shape 不同时，preflight 是建立安全转换的必填边界。 */
-type CheckPreflightField<AuthoredOptions extends object, PreparedOptions extends object> = HasSameOptionsShape<AuthoredOptions, PreparedOptions> extends true ? Readonly<{
-    readonly preflight?: CheckPreflight<AuthoredOptions, PreparedOptions>;
+/** Prepared shape 不同时，preparation 是建立安全转换的必填边界。 */
+type CheckPreparationField<AuthoredOptions extends object, PreparedOptions extends object> = HasSameOptionsShape<AuthoredOptions, PreparedOptions> extends true ? Readonly<{
+    readonly prepare?: CheckPreparation<AuthoredOptions, PreparedOptions>;
 }> : Readonly<{
-    readonly preflight: CheckPreflight<AuthoredOptions, PreparedOptions>;
+    readonly prepare: CheckPreparation<AuthoredOptions, PreparedOptions>;
 }>;
 /**
  * Project Definition 中的普通递归 Check authoring value。
  *
  * @typeParam AuthoredOptions - Definition 中的 declarative options shape。
- * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。
+ * @typeParam PreparedOptions - preparation 后 callback 接收的 invocation-local options shape。
  * @remarks Definition 只闭合 authored JSON options；每个 admitted Check 先在自身 Task lifecycle 内执行
- * preflight，随后才执行 callback。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preflight；同形时可以
+ * preparation，随后才执行 callback。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preparation；同形时可以
  * 省略。它不进入 declarative fingerprint 或 machine output。
  */
-export type Check<AuthoredOptions extends object = object, PreparedOptions extends object = AuthoredOptions> = CheckBase<AuthoredOptions, PreparedOptions> & CheckPreflightField<AuthoredOptions, PreparedOptions>;
+export type Check<AuthoredOptions extends object = object, PreparedOptions extends object = AuthoredOptions> = CheckBase<AuthoredOptions, PreparedOptions> & CheckPreparationField<AuthoredOptions, PreparedOptions> & (ExecutableCheckFields<PreparedOptions, CheckExecutionResult | CheckExecutionResult<Readonly<Record<never, never>>, object>> | ContainerCheckFields);
 export type EmptyCheckOptions = Readonly<Record<never, never>>;
 /**
  * 防止宽泛的 parser 标注擦除 `PromiseLike`。canonical `then` field 可以保存 JSON data，
@@ -314,20 +365,21 @@ type NonThenableData = Readonly<{
  * @remarks Product 不调用此 parser；provider 负责不受信任或跨版本 data 的业务验证。
  */
 export type CheckDataParser<FinalData extends object = object> = (this: void, data: CanonicalJsonObject) => FinalData & NonThenableData;
-type CheckAuthoringBase<Id extends string, AuthoredOptions extends object, PreparedOptions extends object> = Omit<CheckBase<AuthoredOptions, PreparedOptions>, "checkId" | "execution" | "options"> & CheckPreflightField<AuthoredOptions, PreparedOptions> & Readonly<{
+type CheckAuthoringBase<Id extends string, AuthoredOptions extends object, PreparedOptions extends object> = Omit<CheckBase<AuthoredOptions, PreparedOptions>, "checkId" | "handoff" | "options"> & CheckPreparationField<AuthoredOptions, PreparedOptions> & Readonly<{
     readonly checkId: Id;
 }>;
-interface OrdinaryCheckFields<PreparedOptions extends object> {
-    execution?(this: void, context: CheckExecutionContext<PreparedOptions>): CheckResult | Promise<CheckResult>;
-    readonly parseData?: never;
-}
+/** Ordinary Check branches cannot declare typed-provider parsing or private handoff. */
+type OrdinaryCheckRestrictions = HandoffForbidden & Readonly<{
+    parseData?: undefined;
+}>;
+type OrdinaryCheckFields<PreparedOptions extends object> = (ExecutableCheckFields<PreparedOptions> & OrdinaryCheckRestrictions) | (ContainerCheckFields & OrdinaryCheckRestrictions);
 export type CheckWithOptions<Id extends string, AuthoredOptions extends object, PreparedOptions extends object = AuthoredOptions> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> & OrdinaryCheckFields<PreparedOptions> & Readonly<{
     readonly options: AuthoredOptions;
 }>;
 export type CheckWithoutOptions<Id extends string> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> & OrdinaryCheckFields<EmptyCheckOptions> & Readonly<{
     readonly options?: never;
 }>;
-interface TypedCheckFields<PreparedOptions extends object, Parser extends CheckDataParser> {
+interface TypedCheckFields<PreparedOptions extends object, Parser extends CheckDataParser> extends ExecutableCheckFields<PreparedOptions, CheckExecutionResult<NoInfer<ReturnType<Parser>>>> {
     /**
      * 将 canonical runtime data 还原为 provider data。
      *
@@ -336,14 +388,49 @@ interface TypedCheckFields<PreparedOptions extends object, Parser extends CheckD
      * 也不验证不受信任输入。
      */
     readonly parseData: Parser;
-    execution(this: void, context: CheckExecutionContext<PreparedOptions>): CheckResult<NoInfer<ReturnType<Parser>>> | Promise<CheckResult<NoInfer<ReturnType<Parser>>>>;
+    readonly handoff?: never;
 }
+interface HandoffCheckFields<PreparedOptions extends object, Handoff extends object> extends ExecutableCheckFields<PreparedOptions, CheckExecutionResult<object, Handoff>> {
+    readonly handoff: true;
+    readonly parseData?: undefined;
+}
+interface TypedHandoffCheckFields<PreparedOptions extends object, Parser extends CheckDataParser, Handoff extends object> extends ExecutableCheckFields<PreparedOptions, CheckExecutionResult<NoInfer<ReturnType<Parser>>, Handoff>> {
+    readonly handoff: true;
+    readonly parseData: Parser;
+}
+/** Extracts the private reference type from an already-validated passed terminal result. */
+type HandoffFromTerminalResult<Result> = Extract<Awaited<Result>, {
+    readonly status: "passed";
+}> extends {
+    readonly handoff: infer Handoff;
+} ? Handoff extends object ? Handoff : never : never;
+type PassedHandoffResult<Result> = Extract<Awaited<Result>, {
+    readonly status: "passed";
+}>;
+/** Every passed branch must accept the complete inferred handoff type, not just one union member. */
+type PassedHandoffBranchIsConsistent<Passed, Handoff> = Passed extends {
+    readonly handoff: infer BranchHandoff;
+} ? [Handoff] extends [BranchHandoff] ? true : false : false;
+type HandoffTerminalResultConstraint<Result> = false extends PassedHandoffBranchIsConsistent<PassedHandoffResult<Result>, HandoffFromTerminalResult<Result>> ? never : unknown;
+type HandoffExecution<PreparedOptions extends object, FinalData extends object = object> = (this: void, context: CheckExecutionContext<PreparedOptions>) => CheckExecutionResult<FinalData, object>;
 export type TypedCheckWithOptions<Id extends string, AuthoredOptions extends object, Parser extends CheckDataParser, PreparedOptions extends object = AuthoredOptions> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> & TypedCheckFields<PreparedOptions, Parser> & Readonly<{
     readonly options: AuthoredOptions;
 }>;
 export type TypedCheckWithoutOptions<Id extends string, Parser extends CheckDataParser> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> & TypedCheckFields<EmptyCheckOptions, Parser> & Readonly<{
     readonly options?: never;
 }>;
+export type HandoffCheckWithOptions<Id extends string, AuthoredOptions extends object, Handoff extends object, PreparedOptions extends object = AuthoredOptions> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> & HandoffCheckFields<PreparedOptions, Handoff> & Readonly<{
+    readonly options: AuthoredOptions;
+}>;
+export type HandoffCheckWithoutOptions<Id extends string, Handoff extends object> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> & HandoffCheckFields<EmptyCheckOptions, Handoff> & Readonly<{
+    readonly options?: never;
+}>;
+export type TypedHandoffCheckWithOptions<Id extends string, AuthoredOptions extends object, Parser extends CheckDataParser, Handoff extends object, PreparedOptions extends object = AuthoredOptions> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> & TypedHandoffCheckFields<PreparedOptions, Parser, Handoff> & Readonly<{
+    readonly options: AuthoredOptions;
+}>;
+export type TypedHandoffCheckWithoutOptions<Id extends string, Parser extends CheckDataParser, Handoff extends object> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> & TypedHandoffCheckFields<EmptyCheckOptions, Parser, Handoff> & Readonly<{
+    readonly options?: never;
+}>;
 /**
  * 定义一个 Check，同时保留 literal `checkId`、options 与 typed-provider parser 的 inference。
  *
@@ -366,13 +453,13 @@ export type TypedCheckWithoutOptions<Id extends string, Parser extends CheckData
  *   checkId: "license-policy",
  *   displayName: "License policy",
  *   options: { denied: ["GPL-3.0-only"] },
- *   preflight(options) {
+ *   prepare(options) {
  *     return hasValidLicensePolicyOptions(options)
  *       ? { status: "success", preparedOptions: options }
  *       : { status: "failure", action: "block", reason: { code: "invalid-options" } };
  *   },
- *   visibility: "attention",
- *   execution({ options, records, signal }) {
+ *   omitQuietPassedRow: true,
+ *   execute({ options, records, signal }) {
  *     if (signal.aborted) return { status: "unavailable", reason: { code: "cancelled" } };
  *
  *     const deniedCount = options.denied.length;
@@ -389,6 +476,30 @@ export type TypedCheckWithoutOptions<Id extends string, Parser extends CheckData
  * });
  * ```
  */
+export declare function defineCheck<const Id extends string, AuthoredOptions extends object, const Execution extends HandoffExecution<PreparedOptions>, PreparedOptions extends object = AuthoredOptions>(value: CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> & Readonly<{
+    readonly handoff: true;
+    readonly options: AuthoredOptions;
+    readonly parseData?: undefined;
+    readonly execute: Execution;
+}> & HandoffTerminalResultConstraint<ReturnType<Execution>>): HandoffCheckWithOptions<Id, AuthoredOptions, HandoffFromTerminalResult<ReturnType<Execution>>, PreparedOptions> & CheckHandoffProvider<Id, HandoffFromTerminalResult<ReturnType<Execution>>>;
+export declare function defineCheck<const Id extends string, const Execution extends HandoffExecution<EmptyCheckOptions>>(value: CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> & Readonly<{
+    readonly handoff: true;
+    readonly options?: never;
+    readonly parseData?: undefined;
+    readonly execute: Execution;
+}> & HandoffTerminalResultConstraint<ReturnType<Execution>>): HandoffCheckWithoutOptions<Id, HandoffFromTerminalResult<ReturnType<Execution>>> & CheckHandoffProvider<Id, HandoffFromTerminalResult<ReturnType<Execution>>>;
+export declare function defineCheck<const Id extends string, AuthoredOptions extends object, const Parser extends CheckDataParser, const Execution extends HandoffExecution<PreparedOptions, NoInfer<ReturnType<Parser>>>, PreparedOptions extends object = AuthoredOptions>(value: CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> & Readonly<{
+    readonly handoff: true;
+    readonly options: AuthoredOptions;
+    readonly parseData: Parser;
+    readonly execute: Execution;
+}> & HandoffTerminalResultConstraint<ReturnType<Execution>>): TypedHandoffCheckWithOptions<Id, AuthoredOptions, Parser, HandoffFromTerminalResult<ReturnType<Execution>>, PreparedOptions> & CheckHandoffProvider<Id, HandoffFromTerminalResult<ReturnType<Execution>>>;
+export declare function defineCheck<const Id extends string, const Parser extends CheckDataParser, const Execution extends HandoffExecution<EmptyCheckOptions, NoInfer<ReturnType<Parser>>>>(value: CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> & Readonly<{
+    readonly handoff: true;
+    readonly options?: never;
+    readonly parseData: Parser;
+    readonly execute: Execution;
+}> & HandoffTerminalResultConstraint<ReturnType<Execution>>): TypedHandoffCheckWithoutOptions<Id, Parser, HandoffFromTerminalResult<ReturnType<Execution>>> & CheckHandoffProvider<Id, HandoffFromTerminalResult<ReturnType<Execution>>>;
 export declare function defineCheck<const Id extends string, AuthoredOptions extends object, PreparedOptions extends object = AuthoredOptions>(value: CheckWithOptions<Id, AuthoredOptions, PreparedOptions>): CheckWithOptions<Id, AuthoredOptions, PreparedOptions>;
 export declare function defineCheck<const Id extends string>(value: CheckWithoutOptions<Id>): CheckWithoutOptions<Id>;
 export declare function defineCheck<const Id extends string, AuthoredOptions extends object, const Parser extends CheckDataParser, PreparedOptions extends object = AuthoredOptions>(value: TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>): TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>;

package/types/check/flag-enablement.d.ts

@@ -0,0 +1,42 @@
+/** 一个递归 flag presence 条件表达式。字符串是唯一 leaf；operator 保留 author child 顺序和 multiplicity。 */
+export type CheckFlagCondition = string | Readonly<{
+    readonly kind: "all" | "any" | "none" | "not-all" | "exactly-one";
+    readonly conditions: readonly [CheckFlagCondition, ...CheckFlagCondition[]];
+}> | Readonly<{
+    readonly kind: "not";
+    readonly condition: CheckFlagCondition;
+}>;
+type CheckFlagConditionSetKind = "all" | "any" | "none" | "not-all" | "exactly-one";
+type NonEmptyFlagConditions = readonly [CheckFlagCondition, ...CheckFlagCondition[]];
+type CheckFlagConditionSet<Kind extends CheckFlagConditionSetKind> = Readonly<{
+    readonly kind: Kind;
+    readonly conditions: NonEmptyFlagConditions;
+}>;
+type CheckFlagNegation = Readonly<{
+    readonly kind: "not";
+    readonly condition: CheckFlagCondition;
+}>;
+/** 构造 `all` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export declare function all(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"all">;
+/** 构造 `any` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export declare function any(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"any">;
+/** 构造 `none` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export declare function none(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"none">;
+/** 构造 `not-all` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export declare function notAll(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"not-all">;
+/** 构造 `exactly-one` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export declare function exactlyOne(...conditions: NonEmptyFlagConditions): CheckFlagConditionSet<"exactly-one">;
+/** 构造 `not` 条件；Definition 仍负责 validation、snapshot 与 freeze。 */
+export declare function not(condition: CheckFlagCondition): CheckFlagNegation;
+/** 为一个已声明的 project change ID 生成保留 flag token。 */
+export declare function changeFlag<const Id extends string>(id: Id): `vibe-check:change:${Id}`;
+/** executable Check 的 flag 选择控制。 */
+export interface CheckFlagEnablement {
+    readonly when: CheckFlagCondition;
+    /**
+     * 条件命中时是否启动本 Check 的传递 `dependsOn` prerequisite；省略时只选择直接命中 Check。
+     * `observes` 不参与此选择，且 dependency 自己的 flag 条件不会阻止已启动 prerequisite。
+     */
+    readonly propagateDependsOn?: true;
+}
+export {};

package/types/check/handoff-provider-identity.d.ts

@@ -0,0 +1,12 @@
+declare const HANDOFF_PROVIDER_IDENTITY_BRAND: unique symbol;
+/** Opaque same-package identity retained only by Definition and invocation execution. */
+export type HandoffProviderIdentity = Readonly<{
+    readonly [HANDOFF_PROVIDER_IDENTITY_BRAND]: true;
+}>;
+/** Registers the identity that makes a `handoff: true` Check authentic to this package runtime. */
+export declare function registerHandoffProviderIdentity(value: object): void;
+/** Returns the same-package identity registered by `defineCheck`. */
+export declare function getDefinedHandoffProviderIdentity(value: unknown): HandoffProviderIdentity | undefined;
+/** Preserves a Definition-validated provider identity during materialization. */
+export declare function bindHandoffProviderIdentity(value: object, identity: HandoffProviderIdentity): void;
+export {};

package/types/check/project-changes.d.ts

@@ -0,0 +1,13 @@
+/** 已配置的 project change preparation 产生的 file-centric evidence。 */
+export type ProjectChanges = Readonly<{
+    readonly ok: true;
+    readonly files: readonly Readonly<{
+        readonly path: string;
+        readonly flags: readonly string[];
+    }>[];
+} | {
+    readonly ok: false;
+    readonly reason: Readonly<{
+        readonly code: string;
+    }>;
+}>;

package/types/check/project-context.d.ts

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

package/types/check-settlement/facts.d.ts

@@ -2,7 +2,7 @@ import type { CheckDescriptor } from "../check/descriptor.ts";
 import type { CheckOutcome } from "../check/check.ts";
 export type { CanonicalJsonObject, CanonicalJsonPrimitive, CanonicalJsonValue } from "../data-boundary/canonical-data.ts";
 export type { CheckDescriptor, CheckOutcome };
-/** A Core Check has exactly one terminal outcome and no execution bookkeeping. */
+/** Core Check 恰有一个 terminal outcome，不携带 execution bookkeeping。 */
 export interface CoreCheck extends CheckDescriptor {
     readonly outcome: CheckOutcome;
 }

package/types/data-boundary/canonical-data.d.ts

@@ -1,13 +1,36 @@
 import type { CanonicalJsonObject, CanonicalJsonValue } from "./canonical-json.ts";
 export type { CanonicalJsonObject, CanonicalJsonPrimitive, CanonicalJsonValue } from "./canonical-json.ts";
 /**
- * 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 declare function canonicalizeJsonObject(value: unknown): CanonicalJsonObject | 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 declare function canonicalizeJsonValue(value: unknown): CanonicalJsonValue | undefined;
-/** Serializes detached canonical JSON with explicit lexical object-key ordering. */
+/**
+ * 规范化输入后生成确定性的无额外空白 JSON 文本。
+ *
+ * 对象键按固定的 lexical `<` 顺序输出，不承诺遵循外部 canonical-JSON 标准。即使同一对象已经过
+ * 规范化，`JSON.stringify` 仍按 ECMAScript 的整数索引键顺序输出，不能替代本函数。输入规则与 Proxy
+ * 边界同 `canonicalizeJsonValue`；无效输入或无法反射的 Proxy 均抛出 `TypeError`。
+ */
 export declare function canonicalJsonText(value: unknown): string;
-/** Emits canonical UTF-8 JSON without invoking author getters or `toJSON`. */
+/**
+ * 规范化输入后生成与 `canonicalJsonText` 相同的确定性 UTF-8 JSON 字节。
+ *
+ * 函数自行完成规范化与固定键排序，不要求调用方先取得 canonical JSON 值。输入规则、Proxy 边界和
+ * `TypeError` 失败方式与 `canonicalJsonText` 相同。
+ */
 export declare function canonicalJsonBytes(value: unknown): Uint8Array;

package/types/data-boundary/canonical-json.d.ts

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

package/types/data-boundary/closed-values.d.ts

@@ -1,7 +1,23 @@
 export declare function snapshotPlainRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
 export declare function snapshotClosedRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
-/** Snapshots a closed plain record only when it has exactly the declared own keys. */
+/**
+ * 取得字段集合恰好匹配调用方字段表的闭合普通记录外层浅快照。
+ *
+ * 输入必须是使用 `Object.prototype` 或 null prototype 的非数组对象，且每个自有属性都是可枚举数据属性。
+ * 调用方持有的 `keys` 必须是稳定、无重复的字符串列表；缺字段、多字段、symbol 键、存取器或不可枚举属性
+ * 均返回 `undefined`。成功结果是使用 `Object.prototype` 的冻结浅副本：只固定外层字段，保留 callback、
+ * `undefined` 与嵌套对象或数组的原引用，调用方仍须逐字段验证。这不是 JSON 验证器；不调用 getter，
+ * 但反射 Proxy 可能执行其 trap，反射失败时返回 `undefined`。
+ */
 export declare function snapshotExactClosedRecord(value: unknown, keys: readonly string[]): Readonly<Record<string, unknown>> | undefined;
+/**
+ * 取得标准无空洞数组的外层浅快照。
+ *
+ * 输入必须使用 `Array.prototype`，除标准 `length` 和可枚举索引外没有其它自有属性，也不能包含存取器；
+ * 稀疏数组、额外属性或其它不符合条件的输入返回 `undefined`。成功结果是冻结浅副本，只固定数组结构，
+ * 保留 callback、`undefined` 与嵌套值的原引用，不检查元素的业务类型或 JSON 合法性。不调用存取器，
+ * 但反射 Proxy 可能执行其 trap，反射失败时返回 `undefined`。
+ */
 export declare function snapshotClosedArray(value: unknown): readonly unknown[] | undefined;
 export declare function hasExactPlainRecordKeys(value: Readonly<Record<string, unknown>>, keys: readonly string[]): boolean;
 export declare function hasRequiredAndOptionalRecordKeys(value: Readonly<Record<string, unknown>>, keys: Readonly<{

package/types/data-boundary/config-glob.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Product config glob's single matcher boundary. Candidates use slash form;
+ * dot paths participate only when an explicit glob matches them.
+ */
+export declare function matchesAnyConfigGlob(candidatePath: string, configGlobs: readonly string[]): boolean;

package/types/data-boundary/project-path.d.ts

@@ -0,0 +1,4 @@
+/** Converts a host path spelling to the Product's slash-path form. */
+export declare function toSlashPath(filePath: string): string;
+/** Recognizes one stable project-root-relative slash path. */
+export declare function isNormalizedProjectRelativePath(value: unknown): value is string;