@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/project-run/task-scheduler/scheduler.ts

@@ -1,22 +1,17 @@
-import { prepareTaskGraph, type PlannedTask } from "./graph.ts";
-import { diagnosticTags } from "../diagnostic-logging/logger.ts";
+import type { AdmissionPolicyContext } from "../../project-definition/project-definition.ts";
+import { prepareTaskGraph } from "./graph.ts";
 import {
   decideScheduler,
   type SchedulerDecision,
   type SchedulerTrigger
 } from "./scheduler-decision.ts";
 import {
-  cancelPendingTasks,
   createSchedulerState,
-  recordSettlement,
   snapshotSchedulerState,
-  type RunningTaskCompletion,
   type RunTaskGraphOptions,
   type SchedulerState,
-  type TaskGraphRun,
-  type TaskSettlement
+  type TaskGraphRun
 } from "./execution-state.ts";
-
 export type {
   RunTaskGraphOptions,
   SettledTask,
@@ -24,35 +19,217 @@ export type {
   TaskGraphRun,
   TaskSettlement
 } from "./execution-state.ts";
+import { AdmissionPolicyFault } from "./scheduler-admission-decision.ts";
+import { replayCoreForcedBlocks } from "./forced-block-effect-replay.ts";
+import { SchedulerPerformanceDiagnostics } from "./measurement/diagnostics.ts";
+import {
+  observeAdmissionPolicyFault,
+  observeSchedulerDecision,
+  observeSchedulerGraph,
+  performanceState
+} from "./scheduler-observation.ts";
+import { observeTerminalMeasurement } from "./scheduler-terminal-measurement.ts";
+import {
+  applyAdmission,
+  applyAdmissionPolicyFault,
+  applyBlockedSettlement,
+  applyCancellation,
+  buildTaskGraphRun,
+  nextRunningSettlement,
+  settleRunningTask
+} from "./scheduler-task-lifecycle.ts";
+import {
+  cancelPendingAdmissionCore,
+  reconcileAdmissionCore,
+  selectAdmissionCore,
+  settleRunningAdmissionCore,
+  type AdmissionCoreEffect
+} from "./admission-core/core.ts";
 
 export async function runTaskGraph<TResult>(
   options: RunTaskGraphOptions<TResult>
 ): Promise<TaskGraphRun<TResult>> {
   const graph = prepareTaskGraph(options.graph, options.maxParallel);
   const state = createSchedulerState(graph, options);
+  observeSchedulerGraph(state);
+  const measurementInput =
+    options.performanceDiagnostics ??
+    (state.admissionPolicy.requiresMeasurement === true
+      ? Object.freeze({
+          clock: Object.freeze({ now: () => performance.now() }),
+          declarativeFingerprint: ""
+        })
+      : undefined);
+  const diagnostics =
+    measurementInput === undefined
+      ? undefined
+      : new SchedulerPerformanceDiagnostics(measurementInput, performanceState(state));
+  const initialReconciliation = reconcileAdmissionCore(state.admissionCore);
+  replayCoreForcedBlocks(
+    state,
+    initialReconciliation.effects,
+    initialReconciliation.effectStates,
+    diagnostics,
+    triggerForInitialReconciliation()
+  );
   let trigger: SchedulerTrigger = Object.freeze({ kind: "execution-started" });
 
   while (true) {
-    const decision = decideScheduler(snapshotSchedulerState(state), trigger);
-    observeSchedulerDecision(state, decision);
+    let decision: SchedulerDecision;
+    try {
+      const snapshot = snapshotSchedulerState(state);
+      const measurement =
+        state.admissionPolicy.requiresMeasurement === true
+          ? () => decisionBoundaryMeasurement(diagnostics)
+          : undefined;
+      decision =
+        diagnostics?.measureControlPath(() =>
+          decideScheduler(
+            snapshot,
+            trigger,
+            state.admissionPolicy,
+            measurement,
+            state.admissionCore
+          )
+        ) ??
+        decideScheduler(snapshot, trigger, state.admissionPolicy, measurement, state.admissionCore);
+    } catch (error) {
+      if (!(error instanceof AdmissionPolicyFault)) throw error;
+      const cancellation = cancelPendingAdmissionCore(state.admissionCore);
+      state.admissionCore = cancellation.state;
+      diagnostics?.beforePendingSettlement(state.pending.map((task) => task.id));
+      if (diagnostics === undefined) applyAdmissionPolicyFault(state, error);
+      else diagnostics.measureControlPath(() => applyAdmissionPolicyFault(state, error));
+      diagnostics?.captureState(performanceState(state));
+      observeAdmissionPolicyFault(state, error);
+      trigger = Object.freeze({ kind: "cancellation-applied" });
+      continue;
+    }
+    observeSchedulerDecision(state, decision, diagnostics);
 
     switch (decision.kind) {
-      case "admit":
-        applyAdmission(state, decision);
+      case "admit": {
+        if (state.signal?.aborted === true) {
+          const cancellation = cancelPendingAdmissionCore(state.admissionCore);
+          state.admissionCore = cancellation.state;
+          diagnostics?.beforePendingSettlement(state.pending.map((task) => task.id));
+          const lifecycleFault = new AdmissionPolicyFault("lifecycle-invalid-select");
+          if (diagnostics === undefined) applyAdmissionPolicyFault(state, lifecycleFault);
+          else
+            diagnostics.measureControlPath(() => applyAdmissionPolicyFault(state, lifecycleFault));
+          diagnostics?.captureState(performanceState(state));
+          observeAdmissionPolicyFault(state, lifecycleFault);
+          trigger = Object.freeze({ kind: "cancellation-applied" });
+          continue;
+        }
+        const selection = selectAdmissionCore(state.admissionCore, decision.taskId);
+        if (!selection.accepted) {
+          throw new Error("shared admission core rejected a Scheduler hard-guarded selection");
+        }
+        const admissionEffect = selection.transition.effects[0];
+        if (admissionEffect === undefined) {
+          throw new Error("shared admission core omitted a Scheduler admission effect");
+        }
+        state.admissionCore = selection.transition.state;
+        diagnostics?.beforeAdmission(decision.taskId, [...state.runningById.keys()]);
+        if (diagnostics === undefined) applyAdmission(state, decision);
+        else diagnostics.measureControlPath(() => applyAdmission(state, decision));
+        diagnostics?.captureState(performanceState(state));
+        if (state.admissionPolicy.requiresMeasurement === true) {
+          diagnostics?.beginSelectedPolicyAction(decision.taskId);
+          diagnostics?.recordEffect(Object.freeze({ kind: "admitted", taskId: decision.taskId }));
+        }
+        observeAdmissionCoreEffect(state, admissionEffect);
         trigger = Object.freeze({ kind: "admission-continued" });
         continue;
+      }
       case "settle-blocked":
-        applyBlockedSettlement(state, decision);
-        trigger = Object.freeze({ kind: "blocked-settled", taskId: decision.taskId });
+        diagnostics?.beforePendingSettlement([decision.taskId]);
+        if (diagnostics === undefined) applyBlockedSettlement(state, decision);
+        else diagnostics.measureControlPath(() => applyBlockedSettlement(state, decision));
+        diagnostics?.captureState(performanceState(state));
+        diagnostics?.recordEffect(
+          Object.freeze({
+            kind: "settled",
+            settlementKind: "blocked",
+            taskId: decision.taskId
+          })
+        );
+        trigger = Object.freeze({
+          kind: "blocked-settled",
+          taskId: decision.taskId
+        });
         continue;
       case "cancel-pending":
-        applyCancellation(state, decision);
+        state.admissionCore = cancelPendingAdmissionCore(state.admissionCore).state;
+        diagnostics?.beforePendingSettlement(decision.taskIds);
+        if (diagnostics === undefined) applyCancellation(state, decision);
+        else diagnostics.measureControlPath(() => applyCancellation(state, decision));
+        diagnostics?.captureState(performanceState(state));
+        for (const taskId of decision.taskIds) {
+          diagnostics?.recordEffect(
+            Object.freeze({
+              kind: "settled",
+              settlementKind: "cancelled-before-start",
+              taskId
+            })
+          );
+        }
         trigger = Object.freeze({ kind: "cancellation-applied" });
         continue;
       case "await-running": {
-        applyReservationUpdate(state, decision.reservationUpdate);
+        if (decision.proposal?.kind === "wait") {
+          diagnostics?.beforeAcceptedWait();
+          if (state.admissionPolicy.requiresMeasurement === true) {
+            diagnostics?.beginWaitPolicyAction();
+          }
+        }
         const completion = await nextRunningSettlement(state);
-        settleRunningTask(state, completion);
+        diagnostics?.beforeRunningSettlement(completion.taskId);
+        if (diagnostics === undefined) settleRunningTask(state, completion);
+        else diagnostics.measureControlPath(() => settleRunningTask(state, completion));
+        const settlementKind = completion.settlement.kind;
+        if (
+          settlementKind !== "completed" &&
+          settlementKind !== "prerequisite-unsatisfied" &&
+          settlementKind !== "failed"
+        ) {
+          throw new Error("running Task completed with a non-running settlement kind");
+        }
+        const transition = settleRunningAdmissionCore(
+          state.admissionCore,
+          completion.taskId,
+          settlementKind
+        );
+        if (!transition.accepted) {
+          throw new Error("shared admission core rejected a Scheduler running settlement");
+        }
+        const directEffect = transition.transition.effects[0];
+        const directState = transition.transition.effectStates[0];
+        if (directEffect === undefined || directState === undefined) {
+          throw new Error("shared admission core omitted a Scheduler running settlement effect");
+        }
+        state.admissionCore = directState;
+        diagnostics?.captureState(performanceState(state));
+        diagnostics?.recordEffect(
+          Object.freeze({
+            kind: "settled",
+            settlementKind: completion.settlement.kind,
+            taskId: completion.taskId
+          })
+        );
+        observeAdmissionCoreEffect(state, directEffect);
+        replayCoreForcedBlocks(
+          state,
+          transition.transition.effects.slice(1),
+          transition.transition.effectStates.slice(1),
+          diagnostics,
+          Object.freeze({
+            kind: "task-settled",
+            settlementKind: completion.settlement.kind,
+            taskId: completion.taskId
+          })
+        );
         trigger = Object.freeze({
           kind: "task-settled",
           settlementKind: completion.settlement.kind,
@@ -60,169 +237,37 @@ export async function runTaskGraph<TResult>(
         });
         continue;
       }
-      case "complete":
-        return buildTaskGraphRun(state);
+      case "complete": {
+        if (diagnostics === undefined) return buildTaskGraphRun(state);
+        const run = diagnostics.measureControlPath(() => buildTaskGraphRun(state));
+        const terminalMeasurement = await observeTerminalMeasurement({
+          diagnostics,
+          options,
+          state
+        });
+        return Object.freeze({ ...run, terminalMeasurement });
+      }
     }
   }
 }
 
-function observeSchedulerDecision<TResult>(
+function observeAdmissionCoreEffect<TResult>(
   state: SchedulerState<TResult>,
-  decision: SchedulerDecision
+  effect: AdmissionCoreEffect
 ): void {
-  state.diagnosticLogger?.observe({
-    event: "scheduler.decision",
-    tags: schedulerDecisionTags(decision),
-    details: decision
-  });
+  if (state.onAdmissionCoreEffect === undefined) return;
+  state.onAdmissionCoreEffect(Object.freeze({ effect, state: state.admissionCore }));
 }
 
-function schedulerDecisionTags(decision: SchedulerDecision): readonly string[] {
-  return diagnosticTags(
-    "SCHEDULER",
-    decision.kind.toUpperCase(),
-    ...("taskId" in decision ? [`TASK:${decision.taskId}`] : [])
-  );
+function triggerForInitialReconciliation(): SchedulerTrigger {
+  return Object.freeze({ kind: "execution-started" });
 }
 
-function applyAdmission<TResult>(
-  state: SchedulerState<TResult>,
-  decision: Extract<SchedulerDecision, { readonly kind: "admit" }>
-): void {
-  const task = takePendingTask(state, decision.taskId, "admission");
-  applyReservationUpdate(state, decision.reservationUpdate);
-  for (const mutex of task.mutex) {
-    state.runningMutexes.add(mutex);
+function decisionBoundaryMeasurement(
+  diagnostics: SchedulerPerformanceDiagnostics | undefined
+): AdmissionPolicyContext["measurement"] {
+  if (diagnostics === undefined) {
+    throw new Error("custom policy measurement collector is unavailable");
   }
-  activateScope(state, decision.scopeToActivate);
-
-  const completion = Promise.resolve()
-    .then(() => state.execute(task, Object.freeze({ signal: state.signal })))
-    .then((value) => completedTaskCompletion(task.id, value))
-    .catch((error: unknown) => failedTaskCompletion<TResult>(task.id, error));
-  state.runningById.set(task.id, { task, completion });
-}
-
-function activateScope<TResult>(state: SchedulerState<TResult>, scopeId: string | null): void {
-  if (scopeId === null) return;
-  const scope = state.scopesById.get(scopeId);
-  if (scope === undefined)
-    throw new Error(`scheduler admission references unknown scope ${scopeId}`);
-  scope.isActive = true;
-}
-
-function applyBlockedSettlement<TResult>(
-  state: SchedulerState<TResult>,
-  decision: Extract<SchedulerDecision, { readonly kind: "settle-blocked" }>
-): void {
-  const task = takePendingTask(state, decision.taskId, "blocked settlement");
-  recordSettlement(
-    state,
-    task,
-    Object.freeze({ kind: "blocked", dependencyIds: decision.dependencyIds })
-  );
-}
-
-function applyCancellation<TResult>(
-  state: SchedulerState<TResult>,
-  decision: Extract<SchedulerDecision, { readonly kind: "cancel-pending" }>
-): void {
-  const pendingTaskIds = state.pending.map((task) => task.id);
-  if (!sameTaskIds(pendingTaskIds, decision.taskIds)) {
-    throw new Error("scheduler cancellation decision no longer matches pending tasks");
-  }
-  if ((state.reservationTaskId ?? null) !== decision.reservation.taskId) {
-    throw new Error("scheduler cancellation decision no longer matches reservation state");
-  }
-  cancelPendingTasks(state);
-}
-
-function applyReservationUpdate<TResult>(
-  state: SchedulerState<TResult>,
-  reservation: Extract<
-    SchedulerDecision,
-    { readonly kind: "admit" | "await-running" }
-  >["reservationUpdate"]
-): void {
-  switch (reservation.kind) {
-    case "unchanged":
-      return;
-    case "set":
-      state.reservationTaskId = reservation.taskId;
-      return;
-    case "clear":
-      state.reservationTaskId = undefined;
-      return;
-  }
-}
-
-function takePendingTask<TResult>(
-  state: SchedulerState<TResult>,
-  taskId: string,
-  action: string
-): PlannedTask {
-  const index = state.pending.findIndex((task) => task.id === taskId);
-  if (index < 0) throw new Error(`task ${taskId} is not pending for ${action}`);
-  const [task] = state.pending.splice(index, 1);
-  if (task === undefined) throw new Error(`task ${taskId} disappeared during ${action}`);
-  return task;
-}
-
-async function nextRunningSettlement<TResult>(
-  state: SchedulerState<TResult>
-): Promise<RunningTaskCompletion<TResult>> {
-  if (state.runningById.size === 0) {
-    throw new Error("scheduler cannot await a task when no task is running");
-  }
-  return Promise.race([...state.runningById.values()].map((running) => running.completion));
-}
-
-function settleRunningTask<TResult>(
-  state: SchedulerState<TResult>,
-  result: RunningTaskCompletion<TResult>
-): void {
-  const running = state.runningById.get(result.taskId);
-  if (running === undefined) {
-    throw new Error(`task ${result.taskId} settled without admission`);
-  }
-  state.runningById.delete(result.taskId);
-  for (const mutex of running.task.mutex) {
-    state.runningMutexes.delete(mutex);
-  }
-  recordSettlement(state, running.task, result.settlement);
-}
-
-function completedTaskCompletion<TResult>(
-  taskId: string,
-  value: TResult
-): RunningTaskCompletion<TResult> {
-  const settlement: TaskSettlement<TResult> = { kind: "completed", value };
-  return Object.freeze({ taskId, settlement: Object.freeze(settlement) });
-}
-
-function failedTaskCompletion<TResult>(
-  taskId: string,
-  error: unknown
-): RunningTaskCompletion<TResult> {
-  const settlement: TaskSettlement<TResult> = { kind: "failed", error };
-  return Object.freeze({ taskId, settlement: Object.freeze(settlement) });
-}
-
-function buildTaskGraphRun<TResult>(state: SchedulerState<TResult>): TaskGraphRun<TResult> {
-  return Object.freeze({
-    cancelled: state.isCancelled,
-    settlements: Object.freeze(
-      state.graph.tasks.map((task) => {
-        const settlement = state.settlementsByTaskId.get(task.id);
-        if (settlement === undefined) {
-          throw new Error(`task ${task.id} was not settled`);
-        }
-        return Object.freeze({ task, settlement });
-      })
-    )
-  });
-}
-
-function sameTaskIds(left: readonly string[], right: readonly string[]): boolean {
-  return left.length === right.length && left.every((taskId, index) => taskId === right[index]);
+  return diagnostics.policyMeasurement();
 }

package/types/cache/cache-json-by-key.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `cacheJsonByKey` 的 caller-owned identity、payload parser 与 computation。
+ *
+ * `key` 必须覆盖所有会改变 computation 结果的输入、实现、options、toolchain 与声明的外部状态；
+ * 不能放入 secret 或低熵敏感值。`directory` 是调用方信任、可自行删除的本地状态空间。
+ */
+type NonThenable<T extends object> = T & Readonly<{
+    readonly then?: undefined;
+}>;
+/** Caller-keyed JSON cache 的 options。 */
+export interface CacheJsonByKeyOptions<T extends object> {
+    /** cache miss、读取失败或 payload 无效时执行的 sync/async computation。 */
+    readonly compute: () => unknown;
+    /** 调用方信任、可自行清理的 absolute local directory。 */
+    readonly directory: string;
+    /** 覆盖所有影响 computation 结果的完整 semantic key；不得包含 secret 或低熵敏感值。 */
+    readonly key: string;
+    /** 调用方为这一类缓存选择的非空 identity namespace。 */
+    readonly namespace: string;
+    /** 同步验证 cached/computed canonical JSON object，并返回调用方的 typed value。 */
+    readonly parse: (value: unknown) => NonThenable<T>;
+    /** 调用方控制、在 payload 或 computation contract 改变时更新的非空版本。 */
+    readonly version: string;
+}
+/** `cacheJsonByKey` 返回的闭合 cache observation 与本次 parser value。 */
+export type CacheJsonByKeyResult<T extends object> = Readonly<{
+    /** 已读取并通过 parser 验证现有 payload。 */
+    readonly read: "hit";
+    /** 本次 value 来自 cache，不调用 `compute`。 */
+    readonly source: "cache";
+    /** `parse` 返回的调用方 typed value。 */
+    readonly value: T;
+    /** cache hit 不尝试重新写入。 */
+    readonly write: "not-attempted";
+}> | Readonly<{
+    /** 没有 entry、读取失败，或已有 payload 未通过 identity/parser 验证。 */
+    readonly read: "failed" | "invalid" | "miss";
+    /** 本次 value 来自成功的 `compute` 与 `parse`。 */
+    readonly source: "computed";
+    /** `parse` 返回的调用方 typed value。 */
+    readonly value: T;
+    /** 新 payload 已存储，或存储失败但 typed value 仍可使用。 */
+    readonly write: "failed" | "stored";
+}>;
+/**
+ * 按 caller 提供的完整 semantic key 复用本地 canonical JSON object。
+ *
+ * cache hit 不会跳过或重放 Check settlement、Records、messages、duration 或 side effects。读取或写入失败
+ * 只通过返回的 observation 可见；只要 `compute` 与 `parse` 成功，就仍返回本次 computation 的 value。
+ * 不提供依赖发现、默认目录、lock/single-flight、TTL/LRU、cleanup、remote cache 或 tamper protection。
+ */
+export declare function cacheJsonByKey<T extends object>(authoredOptions: CacheJsonByKeyOptions<T>): Promise<CacheJsonByKeyResult<T>>;
+export {};

package/types/check/check.d.ts

@@ -36,6 +36,22 @@ export interface CheckResultMessages {
 }
 /** 已结算 Check 在人读 progress 中的可见性。 */
 export type CheckVisibility = "always" | "attention";
+/** 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;
+}
 /**
  * Check callback 的 terminal result。
  *
@@ -100,45 +116,60 @@ 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。 */
+/** 当前 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。
+     * 读取一个直接 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;
+    /**
+     * 枚举当前 Check 的全部已规范化 direct relation outcomes。
+     *
+     * @returns 按有效 direct relation ID 稳定排序、深度冻结的 `{ checkId, outcome }` observations；只含当前
+     * Check 显式或继承得到的 `dependsOn` / `observes` relation，不暴露 scheduler 历史、transitive 或未声明
+     * Check。
+     */
+    list(): readonly DependencyObservation[];
 }
 /** callback 可读取的、由 Product 规范化的项目上下文。 */
 export interface CheckProjectContext {
@@ -153,8 +184,12 @@ export interface CheckProjectContext {
  * @typeParam Options - 此 Check preflight 后传给 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。 */
@@ -221,16 +256,24 @@ interface CheckBase<AuthoredOptions extends object, PreparedOptions extends obje
     readonly displayName: string;
     /** Check-owned declarative options；默认 Check 的嵌套 branch 以普通对象组合替换。 */
     readonly options?: AuthoredOptions;
+    /** 仅当多 flag presence predicate 匹配时启用 executable Check；省略时始终启用。 */
+    readonly enabledByFlags?: CheckFlagEnablement;
     /** 可执行节点的 callback；省略时此节点只承载递归 children。 */
     execution?(this: void, context: CheckExecutionContext<PreparedOptions>): CheckResult | Promise<CheckResult>;
     /** 继承 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>;
+    /** 静态 named resource claims；省略时继承，显式 mapping 完整替换。 */
+    readonly resourceClaims?: CheckResourceClaims;
     /** 已结算 Check 的人读可见性；可执行节点默认 `always`。 */
     readonly visibility?: CheckVisibility;
 }
@@ -251,9 +294,9 @@ type CheckPreflightField<AuthoredOptions extends object, PreparedOptions extends
  *
  * @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。
+ * @remarks Definition 只闭合 authored JSON options；每个 admitted Check 先在自身 Task lifecycle 内执行
+ * preflight，随后才执行 callback。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preflight；同形时可以
+ * 省略。它不进入 declarative fingerprint 或 machine output。
  */
 export type Check<AuthoredOptions extends object = object, PreparedOptions extends object = AuthoredOptions> = CheckBase<AuthoredOptions, PreparedOptions> & CheckPreflightField<AuthoredOptions, PreparedOptions>;
 export type EmptyCheckOptions = Readonly<Record<never, never>>;
@@ -265,7 +308,7 @@ 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 的业务验证。
@@ -307,6 +350,8 @@ export type TypedCheckWithoutOptions<Id extends string, Parser extends CheckData
  * @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 (