@zxyycom/vibe-check 0.0.1 → 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,10 +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>>;
+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。
  *
@@ -43,27 +51,48 @@ 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<(([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。 */
@@ -86,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。 */
@@ -100,61 +131,104 @@ interface CheckRecordReporter {
     /** 记录一个补充事实；它不决定 Check 的 terminal status。 */
     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";
 }>;
 /** {@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";
     /** 已与原对象脱离的上游依赖终态数据。 */
     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。 */
@@ -170,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
@@ -191,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[];
@@ -211,51 +285,71 @@ 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 转换。
  */
 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。
- * @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>;
+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，
@@ -265,26 +359,27 @@ 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 的业务验证。
  */
 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。
      *
@@ -293,20 +388,57 @@ 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。
  *
  * @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 (
@@ -321,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;
@@ -344,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/inherited-collection.d.ts

@@ -22,7 +22,7 @@ export type InheritedCheckCollection<T> = InheritCheckCollectionInput<T> & Reado
  */
 export type InheritableCheckCollection<T> = readonly T[] | InheritedCheckCollection<T>;
 /**
- * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。
+ * 创建可用于 `dependsOn`、`observes` 或 `mutex` 的受信任继承编辑。
  *
  * @typeParam T - 要添加或移除的 collection item 类型。
  * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。

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/check-settlement/reason-shape.d.ts

@@ -0,0 +1,5 @@
+export type ClosedCheckReason = Readonly<Record<string, unknown>> & Readonly<{
+    readonly code: string;
+}>;
+/** Recognizes the shared closed reason shape before owner-specific ID validation. */
+export declare function isClosedCheckReason(value: Readonly<Record<string, unknown>> | undefined, allowCheckIds: boolean): value is ClosedCheckReason;

package/types/check-settlement/record-store.d.ts

@@ -4,11 +4,11 @@ export type RecordDiagnostic = "record-conflict" | "record-invalid";
 export interface CoreRecordSlot {
     readonly checkId: string;
     readonly diagnostics: Set<RecordDiagnostic>;
-    readonly recordIds: Set<string>;
 }
-/** Holds one Check's minimal Records without inventing a composite string identity. */
+/** Holds Check-local supplemental Records without inventing a composite string identity. */
 export declare class CoreRecordStore {
     #private;
     report(slot: CoreRecordSlot, rawIdentity: unknown, rawData: unknown): RecordSubmissionResult;
+    recordsForCheckInCanonicalOrder(checkId: string): readonly CoreRecord[];
     recordsInCanonicalOrder(): readonly CoreRecord[];
 }