@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/check/check.ts

@@ -1,5 +1,8 @@
 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";
+import { registerHandoffProviderIdentity } from "./handoff-provider-identity.ts";
 
 export {
   inherit,
@@ -47,11 +50,17 @@ 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>>;
+
+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。
@@ -60,36 +69,70 @@ export type CheckVisibility = "always" | "attention";
  * @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<
   (
-    | {
-        /** Check 已产生通过的 final data。 */
-        readonly status: "passed";
-        /** 此 Check 的主要终态事实。 */
-        readonly data: FinalData;
-      }
-    | {
+    | ([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;
-      }
+      } & 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<
   | {
@@ -118,14 +161,12 @@ export type CheckOutcome = Readonly<
     }
 >;
 
-/** 将 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 {
@@ -139,18 +180,18 @@ interface CheckRecordReporter {
   report(identity: RecordIdentityInput, data: object): void;
 }
 
-/** 读取已声明 dependency final data 时的失败原因。 */
+/** 读取已声明 direct relation final data 时的失败原因。 */
 export type DependencyReadError = Readonly<
   | {
-      /** 当前 Check 未声明所请求的 dependency ID。 */
+      /** 当前 Check 未声明所请求的 direct relation ID。 */
       readonly code: "dependency-not-declared";
-      /** 被拒绝的 dependency ID。 */
+      /** 被拒绝的 direct relation ID。 */
       readonly checkId: string;
     }
   | {
       /** 已声明 upstream 没有可读取的 final data。 */
       readonly code: "upstream-data-unavailable";
-      /** 没有 final data 的 direct dependency ID。 */
+      /** 没有 final data 的 direct relation ID。 */
       readonly checkId: string;
       /** 阻止 readback 的 upstream terminal status。 */
       readonly status: "not-applicable" | "unavailable";
@@ -160,9 +201,9 @@ export type DependencyReadError = Readonly<
 /** {@link CheckDependencies.get} 的受控 readback 结果。 */
 export type DependencyReadResult = Readonly<
   | {
-      /** 成功读取 direct dependency final data。 */
+      /** 成功读取 direct relation final data。 */
       readonly ok: true;
-      /** 被读取的 direct dependency ID。 */
+      /** 被读取的 direct relation ID。 */
       readonly checkId: string;
       /** upstream 已结算为 `passed` 或 `failed` 的 status。 */
       readonly status: "passed" | "failed";
@@ -170,40 +211,94 @@ export type DependencyReadResult = Readonly<
       readonly data: CanonicalJsonObject;
     }
   | {
-      /** dependency data 不可读取。 */
+      /** direct relation data 不可读取。 */
       readonly ok: false;
       /** 失败的授权或 upstream-data reason。 */
       readonly error: DependencyReadError;
     }
 >;
 
-/** 当前 Check 的已规范化直接 dependencies 的 data reader。 */
+/** `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。 */
+  readonly checkId: string;
+  /** Core 已结算并冻结的四态 outcome。 */
+  readonly outcome: CheckOutcome;
+}>;
+
+/** 当前 Check 的已规范化直接 relation outcomes 的 data reader。 */
 export interface CheckDependencies {
   /**
-   * 读取一个直接 dependency 的 canonical final data。
+   * 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。
    *
-   * @returns 已声明且为 `passed`/`failed` 的 dependency 返回其 data；未声明或没有 final data 时返回
-   * `ok: false`，不会授权 transitive dependency。
+   * @returns 已声明的 `dependsOn` 或 `observes` relation 且为 `passed`/`failed` 的 Check 返回其 data；
+   * 未声明或没有 final data 时返回 `ok: false`，不会授权 transitive Check。
    */
   get(checkId: string): DependencyReadResult;
-}
 
-/** callback 可读取的、由 Product 规范化的项目上下文。 */
-export interface CheckProjectContext {
-  /** 本次 Run 使用的绝对项目根目录。 */
-  readonly root: string;
-  /** 已去重、排序的 caller-supplied flags。 */
-  readonly flags: readonly string[];
+  /**
+   * 枚举当前 Check 的全部已规范化 direct relation outcomes。
+   *
+   * @returns 按有效 direct relation ID 稳定排序、深度冻结的 `{ checkId, outcome }` observations；只含当前
+   * Check 显式或继承得到的 `dependsOn` / `observes` relation，不暴露 scheduler 历史、transitive 或未声明
+   * Check。
+   */
+  list(): readonly DependencyObservation[];
 }
 
 /**
  * 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 的已声明 direct dependencies。 */
+  /** 当前 Check 的 absolute invocation artifact directory；caller 未授予时为 `null`。 */
+  readonly artifactDirectory: string | null;
+  /** 读取当前 Check 的已声明 direct relations。 */
   readonly dependencies: CheckDependencies;
+  /** 同一次 invocation 内由 Product 统一提供的 identity。 */
+  readonly invocationId: string;
   /** 深度只读、canonical 的 invocation-local prepared Check options。 */
   readonly options: DeepReadonly<Options>;
   /** 已规范化的项目根与 flags。 */
@@ -223,29 +318,30 @@ export interface CheckExecutionContext<Options extends object> {
 export type CheckExecution<Options extends object = object> = (
   this: void,
   context: CheckExecutionContext<Options>
-) => CheckResult | Promise<CheckResult>;
+) => 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<
+export type CheckPreparation<
   AuthoredOptions extends object = object,
   PreparedOptions extends object = AuthoredOptions
 > = {
   bivarianceHack(
     this: void,
     options: DeepReadonly<AuthoredOptions>,
-    signal: AbortSignal
-  ): CheckPreflightResult<PreparedOptions> | Promise<CheckPreflightResult<PreparedOptions>>;
+    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
@@ -253,7 +349,7 @@ export type CheckPreflight<
  * 是 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;
@@ -278,33 +374,52 @@ 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 使用的非空名称。 */
   readonly displayName: string;
   /** Check-owned declarative options；默认 Check 的嵌套 branch 以普通对象组合替换。 */
   readonly options?: AuthoredOptions;
-  /** 可执行节点的 callback；省略时此节点只承载递归 children。 */
-  execution?(
-    this: void,
-    context: CheckExecutionContext<PreparedOptions>
-  ): CheckResult | Promise<CheckResult>;
+  /** 仅当多 flag presence predicate 匹配时启用 executable Check；省略时始终启用。 */
+  readonly enabledByFlags?: CheckFlagEnablement;
+  /** `true` declares an invocation-private handoff on this executable Check. */
+  readonly handoff?: true;
   /** 继承 scheduling context 的 child Checks，不会单独形成 container result。 */
   readonly checks?: readonly Check[];
-  /** 直接 prerequisite Check IDs，或对父 dependency collection 的显式 edit。 */
+  /** 必须全部 `passed` 才能开始当前 Check author work 的直接 prerequisite Check IDs。 */
   readonly dependsOn?: InheritableCheckCollection<string>;
+  /** 等待任意 terminal outcome 并授权当前 Check readback 的直接 observation Check IDs。 */
+  readonly observes?: InheritableCheckCollection<string>;
   /** 此 Check 及其 descendants 的最大并行预算。 */
   readonly maxParallel?: number;
+  /** 同一 ready admission 层级中的静态优先级；省略时继承并最终规范化为 `0`。 */
+  readonly admissionPriority?: number;
   /** 共享资源名称，或对父 mutex collection 的显式 edit。 */
   readonly mutex?: InheritableCheckCollection<string>;
-  /** 已结算 Check 的人读可见性；可执行节点默认 `always`。 */
-  readonly visibility?: CheckVisibility;
+  /** 静态 named resource claims；省略时继承，显式 mapping 完整替换。 */
+  readonly resourceClaims?: CheckResourceClaims;
+}
+
+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 转换。
  */
@@ -316,26 +431,33 @@ type HasSameOptionsShape<AuthoredOptions extends object, PreparedOptions extends
     : false
   : false;
 
-/** Prepared shape 不同时，preflight 是建立安全转换的必填边界。 */
-type CheckPreflightField<AuthoredOptions extends object, PreparedOptions extends object> =
+/** Prepared shape 不同时，preparation 是建立安全转换的必填边界。 */
+type CheckPreparationField<AuthoredOptions extends object, PreparedOptions extends object> =
   HasSameOptionsShape<AuthoredOptions, PreparedOptions> extends true
-    ? Readonly<{ readonly preflight?: CheckPreflight<AuthoredOptions, PreparedOptions> }>
-    : Readonly<{ readonly preflight: CheckPreflight<AuthoredOptions, PreparedOptions> }>;
+    ? Readonly<{ readonly prepare?: CheckPreparation<AuthoredOptions, PreparedOptions> }>
+    : Readonly<{ readonly prepare: CheckPreparation<AuthoredOptions, PreparedOptions> }>;
 
 /**
  * Project Definition 中的普通递归 Check authoring value。
  *
  * @typeParam AuthoredOptions - Definition 中的 declarative options shape。
- * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。
- * @remarks Definition 只闭合 authored JSON options；preflight 在同一 Run 的所有 execution 前作为全局
- * barrier 执行。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preflight；同形时可以省略。它不进入
- * declarative fingerprint 或 machine output。
+ * @typeParam PreparedOptions - preparation 后 callback 接收的 invocation-local options shape。
+ * @remarks Definition 只闭合 authored JSON options；每个 admitted Check 先在自身 Task lifecycle 内执行
+ * 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>;
+  CheckPreparationField<AuthoredOptions, PreparedOptions> &
+  (
+    | ExecutableCheckFields<
+        PreparedOptions,
+        CheckExecutionResult | CheckExecutionResult<Readonly<Record<never, never>>, object>
+      >
+    | ContainerCheckFields
+  );
 
 export type EmptyCheckOptions = Readonly<Record<never, never>>;
 
@@ -346,7 +468,7 @@ export type EmptyCheckOptions = Readonly<Record<never, never>>;
 type NonThenableData = Readonly<{ readonly then?: CanonicalJsonValue }>;
 
 /**
- * 将 canonical dependency data 还原为 provider final-data shape 的同步 parser。
+ * 将 canonical direct-relation data 还原为 provider final-data shape 的同步 parser。
  *
  * @typeParam FinalData - provider 在 `passed`/`failed` result 中声明的 final-data shape。
  * @remarks Product 不调用此 parser；provider 负责不受信任或跨版本 data 的业务验证。
@@ -360,17 +482,16 @@ type CheckAuthoringBase<
   Id extends string,
   AuthoredOptions extends object,
   PreparedOptions extends object
-> = Omit<CheckBase<AuthoredOptions, PreparedOptions>, "checkId" | "execution" | "options"> &
-  CheckPreflightField<AuthoredOptions, PreparedOptions> &
+> = 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,
@@ -392,7 +513,13 @@ export type CheckWithoutOptions<Id extends string> = CheckAuthoringBase<
     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。
    *
@@ -402,12 +529,63 @@ 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,
@@ -428,12 +606,48 @@ export type TypedCheckWithoutOptions<
     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。
  *
  * @remarks 此函数负责 authoring inference；{@link run} 负责 Project Definition validation。
  * @example 定义带 options、Records 与 messages 的自定义 Check
  * ```ts
+ * import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+ *
  * function hasValidLicensePolicyOptions(options: object): boolean {
  *   const denied: unknown = Reflect.get(options, "denied");
  *   return (
@@ -448,13 +662,13 @@ export type TypedCheckWithoutOptions<
  *   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;
@@ -471,6 +685,79 @@ export type TypedCheckWithoutOptions<
  * });
  * ```
  */
+export 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 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 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 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 function defineCheck<
   const Id extends string,
   AuthoredOptions extends object,
@@ -493,5 +780,8 @@ export function defineCheck<const Id extends string, const Parser extends CheckD
   value: TypedCheckWithoutOptions<Id, Parser>
 ): TypedCheckWithoutOptions<Id, Parser>;
 export function defineCheck(value: Check): Check {
+  if (value.handoff === true) {
+    registerHandoffProviderIdentity(value);
+  }
   return value;
 }