@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/project-run/progress-rendering/renderer-formatting.ts

@@ -1,4 +1,10 @@
+import { types } from "node:util";
+
 import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { CoreRecord } from "../../check-settlement/facts.ts";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.ts";
+import { canonicalJsonText } from "../../data-boundary/canonical-data.ts";
+import { FLAG_CONDITION_NOT_MATCHED_CODE } from "../check-execution/flag-controls.ts";
 import type { ProgressFeedback, ProgressOutcomeCounts } from "./renderer.ts";
 
 const COLOR = Object.freeze({
@@ -8,6 +14,8 @@ const COLOR = Object.freeze({
   warning: "\u001B[33m"
 });
 
+const TRUNCATION_MARKER = "… [truncated]";
+
 const NAMED_CONTROL_ESCAPES: Readonly<Partial<Record<string, string>>> = Object.freeze({
   "\n": "\\n",
   "\r": "\\r",
@@ -32,10 +40,35 @@ export function shouldPresentSettledFeedback(
   return (
     feedback.visibility !== "attention" ||
     feedback.outcome.status !== "passed" ||
-    feedback.messages.length > 0
+    feedback.messages.length > 0 ||
+    feedback.records.length > 0
+  );
+}
+
+export function isFlagConditionNotMatchedFeedback(
+  feedback: Extract<ProgressFeedback, { readonly kind: "settled" }>
+): boolean {
+  return (
+    feedback.durationMs === null &&
+    feedback.messages.length === 0 &&
+    feedback.records.length === 0 &&
+    feedback.outcome.status === "not-applicable" &&
+    feedback.outcome.reason?.code === FLAG_CONDITION_NOT_MATCHED_CODE
   );
 }
 
+export function formatFlagConditionNotMatchedBlock(
+  displayNames: readonly [string, ...string[]]
+): string {
+  const subject =
+    displayNames.length === 1
+      ? "The following check did not run because the run flags did not match its condition:"
+      : `The following ${displayNames.length} checks did not run because the run flags did not match their conditions:`;
+  return `  ${subject}\n${displayNames
+    .map((displayName) => `    - ${escapeTerminalText(displayName)}\n`)
+    .join("")}`;
+}
+
 export function formatSettledBlock(
   input: Readonly<{
     readonly completionOrdinal: number;
@@ -43,8 +76,10 @@ export function formatSettledBlock(
     readonly durationMs: number | null;
     readonly messages: readonly CheckMessage[];
     readonly outcome: CheckOutcome;
+    readonly records: readonly CoreRecord[];
     readonly totalChecks: number;
     readonly usesColor: boolean;
+    readonly progressRendering: ResolvedProgressRenderingOutput;
   }>
 ): string {
   const status = statusForOutcome(input.outcome);
@@ -52,7 +87,9 @@ export function formatSettledBlock(
   const duration = input.durationMs === null ? "not run" : formatDuration(input.durationMs);
   const reasonSuffix = reason === undefined ? "" : ` | ${escapeTerminalText(reason)}`;
   const row = `  [${input.completionOrdinal}/${input.totalChecks}] ${escapeTerminalText(input.displayName)} | ${status} | ${duration}${reasonSuffix}\n`;
-  return `${row}${input.messages.map((message) => formatMessage(message, input.usesColor)).join("")}`;
+  const recordPreview = formatRecords(input.records, input.progressRendering);
+  const messagePreview = formatMessages(input.messages, input.usesColor, input.progressRendering);
+  return `${row}${recordPreview}${messagePreview}`;
 }
 
 export function formatFinalSummary(
@@ -72,31 +109,102 @@ export function formatFinalSummary(
   ].join("\n");
 }
 
-function formatMessage(message: CheckMessage, usesColor: boolean): string {
+function formatRecords(
+  records: readonly CoreRecord[],
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
+  return formatPreview(
+    records,
+    (record) => formatRecord(record, progressRendering),
+    "record",
+    progressRendering.recordPreviewLimit
+  );
+}
+
+function formatMessages(
+  messages: readonly CheckMessage[],
+  usesColor: boolean,
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
+  return formatPreview(
+    messages,
+    (message) => formatMessage(message, usesColor, progressRendering),
+    "message",
+    progressRendering.messagePreviewLimit
+  );
+}
+
+function formatPreview<Item>(
+  items: readonly Item[],
+  formatItem: (item: Item) => string,
+  previewKind: "message" | "record",
+  limit: number
+): string {
+  const preview = items.slice(0, limit);
+  const omittedCount = items.length - preview.length;
+  let renderedPreview = "";
+  // Caller formatters run once in selection order; a throw stops the current block.
+  for (const item of preview) renderedPreview += formatItem(item);
+  if (omittedCount === 0) return renderedPreview;
+  return `${renderedPreview}    [${previewKind}s] ${omittedCount} additional ${previewKind}(s) were omitted from terminal preview.\n`;
+}
+
+function formatRecord(
+  record: CoreRecord,
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
+  const defaultText = `${record.id} | ${canonicalJsonText(record.data)}`;
+  const formattedText = formattedPreviewText("record", defaultText, progressRendering);
+  const previewText = boundedTerminalText(
+    formattedText,
+    progressRendering.textPreviewCodePointLimit
+  );
+  return `    [record] ${previewText}\n`;
+}
+
+function formatMessage(
+  message: CheckMessage,
+  usesColor: boolean,
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
   const label = colorMessageLevel(message.level, usesColor);
-  return `    [${label}] ${escapeTerminalText(message.message)}\n`;
+  const formattedText = formattedPreviewText("message", message.message, progressRendering);
+  const previewText = boundedTerminalText(
+    formattedText,
+    progressRendering.textPreviewCodePointLimit
+  );
+  return `    [${label}] ${previewText}\n`;
 }
 
-function totalChecks(counts: ProgressOutcomeCounts): number {
-  return counts.passed + counts.failed + counts.notApplicable + counts.unavailable;
+function formattedPreviewText(
+  kind: "record" | "message",
+  text: string,
+  progressRendering: ResolvedProgressRenderingOutput
+): string {
+  const formatter = progressRendering.formatter;
+  if (formatter === null) return text;
+  const formatted: unknown = formatter(
+    Object.freeze({ kind, maxCodePoints: progressRendering.textPreviewCodePointLimit, text })
+  );
+  if (typeof formatted === "string") return formatted;
+  observeRejectedPromise(formatted);
+  throw new TypeError("Progress preview formatter must synchronously return a string");
 }
 
-function statusForOutcome(outcome: CheckOutcome): ProgressStatus {
-  switch (outcome.status) {
-    case "passed":
-    case "failed":
-      return outcome.status;
-    case "not-applicable":
-      return "not-applicable";
-    case "unavailable":
-      return "unavailable";
+function observeRejectedPromise(value: unknown): void {
+  if (types.isPromise(value)) {
+    // The intrinsic call observes a real Promise without reading a caller-controlled `.then`.
+    // eslint-disable-next-line typescript/no-floating-promises -- rendering must not await formatter misuse.
+    void Promise.prototype.then.call(value, undefined, () => undefined);
   }
 }
 
-function reasonForOutcome(outcome: CheckOutcome): string | undefined {
-  return outcome.status === "passed" || outcome.status === "failed"
-    ? undefined
-    : outcome.reason?.code;
+function boundedTerminalText(value: string, maximumCodePoints: number): string {
+  const escaped = escapeTerminalText(value);
+  if (codePointLength(escaped) <= maximumCodePoints) return escaped;
+  const marker = prefixByCodePoints(TRUNCATION_MARKER, maximumCodePoints);
+  const textBudget = maximumCodePoints - codePointLength(marker);
+  return `${prefixByCodePoints(escaped, textBudget)}${marker}`;
 }
 
 /** Human-only fields must not control the terminal that presents them. */
@@ -116,6 +224,23 @@ function escapeTerminalText(value: string): string {
   return escaped;
 }
 
+function codePointLength(value: string): number {
+  let length = 0;
+  for (const _character of value) length += 1;
+  return length;
+}
+
+function prefixByCodePoints(value: string, limit: number): string {
+  let prefix = "";
+  let length = 0;
+  for (const character of value) {
+    if (length === limit) break;
+    prefix += character;
+    length += 1;
+  }
+  return prefix;
+}
+
 function isTerminalControl(codePoint: number): boolean {
   return (
     codePoint <= 0x1f ||
@@ -132,6 +257,28 @@ function colorMessageLevel(level: CheckMessage["level"], usesColor: boolean): st
 
 type ProgressStatus = CheckOutcome["status"];
 
+function statusForOutcome(outcome: CheckOutcome): ProgressStatus {
+  switch (outcome.status) {
+    case "passed":
+    case "failed":
+      return outcome.status;
+    case "not-applicable":
+      return "not-applicable";
+    case "unavailable":
+      return "unavailable";
+  }
+}
+
+function reasonForOutcome(outcome: CheckOutcome): string | undefined {
+  return outcome.status === "passed" || outcome.status === "failed"
+    ? undefined
+    : outcome.reason?.code;
+}
+
+function totalChecks(counts: ProgressOutcomeCounts): number {
+  return counts.passed + counts.failed + counts.notApplicable + counts.unavailable;
+}
+
 function formatDuration(durationMs: number): string {
   if (durationMs < 1_000) {
     return `${Number.isInteger(durationMs) ? durationMs : Number(durationMs.toFixed(1))}ms`;

package/src/project-run/progress-rendering/renderer-lifecycle.ts

@@ -4,10 +4,13 @@ import type {
   ProgressRenderer,
   ProgressWriter
 } from "./renderer.ts";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.ts";
 import {
+  formatFlagConditionNotMatchedBlock,
   formatFinalSummary,
   formatRunningRow,
   formatSettledBlock,
+  isFlagConditionNotMatchedFeedback,
   shouldPresentSettledFeedback
 } from "./renderer-formatting.ts";
 
@@ -25,14 +28,21 @@ export class ProgressRendererController implements ProgressRenderer {
   private readonly clock: ProgressClock;
   private readonly writer: ProgressWriter;
   private completedCount = 0;
+  private readonly flagConditionNotMatchedDisplayNames: string[] = [];
   private preparedTotal: number | undefined;
   private renderedRunningRows = 0;
   private readonly running: RunningCheck[] = [];
   private readonly usesColor: boolean;
+  private readonly progressRendering: ResolvedProgressRenderingOutput;
 
-  constructor(writer: ProgressWriter, clock: ProgressClock) {
+  constructor(
+    writer: ProgressWriter,
+    clock: ProgressClock,
+    progressRendering: ResolvedProgressRenderingOutput
+  ) {
     this.writer = writer;
     this.clock = clock;
+    this.progressRendering = progressRendering;
     this.refreshesRunningRegion = writer.isTTY && writer.term?.toLowerCase() !== "dumb";
     this.usesColor = this.refreshesRunningRegion && writer.color;
   }
@@ -50,6 +60,9 @@ export class ProgressRendererController implements ProgressRenderer {
       case "prepared":
         this.prepare(feedback.totalChecks);
         return;
+      case "flag-control-completed":
+        this.completeFlagControl();
+        return;
       case "started":
         this.start(feedback);
         return;
@@ -85,7 +98,9 @@ export class ProgressRendererController implements ProgressRenderer {
     if (this.refreshesRunningRegion) this.eraseRunningRegion();
     this.completedCount += 1;
     this.removeRunningCheck(feedback.checkId);
-    if (shouldPresentSettledFeedback(feedback)) {
+    if (isFlagConditionNotMatchedFeedback(feedback)) {
+      this.flagConditionNotMatchedDisplayNames.push(feedback.displayName);
+    } else if (shouldPresentSettledFeedback(feedback)) {
       this.writer.write(
         formatSettledBlock({
           completionOrdinal: this.completedCount,
@@ -93,8 +108,10 @@ export class ProgressRendererController implements ProgressRenderer {
           durationMs: feedback.durationMs,
           messages: feedback.messages,
           outcome: feedback.outcome,
+          records: feedback.records,
           totalChecks,
-          usesColor: this.usesColor
+          usesColor: this.usesColor,
+          progressRendering: this.progressRendering
         })
       );
     }
@@ -106,9 +123,27 @@ export class ProgressRendererController implements ProgressRenderer {
     if (this.running.length > 0) {
       throw new Error("Progress feedback finalized while Checks are still running");
     }
+    this.flushFlagConditionNotMatchedChecks();
     this.writer.write(formatFinalSummary(feedback));
   }
 
+  private completeFlagControl(): void {
+    this.requirePrepared();
+    this.flushFlagConditionNotMatchedChecks();
+  }
+
+  private flushFlagConditionNotMatchedChecks(): void {
+    const firstDisplayName = this.flagConditionNotMatchedDisplayNames[0];
+    if (firstDisplayName === undefined) return;
+    this.writer.write(
+      formatFlagConditionNotMatchedBlock([
+        firstDisplayName,
+        ...this.flagConditionNotMatchedDisplayNames.slice(1)
+      ])
+    );
+    this.flagConditionNotMatchedDisplayNames.length = 0;
+  }
+
   private eraseRunningRegion(): void {
     for (let index = 0; index < this.renderedRunningRows; index += 1) {
       this.writer.write("\u001B[1A\u001B[2K");

package/src/project-run/progress-rendering/renderer.ts

@@ -1,10 +1,14 @@
 import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.ts";
+import type { CoreRecord } from "../../check-settlement/facts.ts";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.ts";
+import { resolveProgressRenderingOutput } from "../../project-definition/output-defaults.ts";
 import { ProgressRendererController } from "./renderer-lifecycle.ts";
 
 export interface ProgressWriter {
   readonly color: boolean;
   readonly isTTY: boolean;
   readonly term: string | undefined;
+  close?(): void;
   write(content: string): void;
 }
 
@@ -13,6 +17,9 @@ export type ProgressFeedback = Readonly<
       readonly kind: "prepared";
       readonly totalChecks: number;
     }
+  | {
+      readonly kind: "flag-control-completed";
+    }
   | {
       readonly kind: "started";
       readonly checkId: string;
@@ -26,6 +33,7 @@ export type ProgressFeedback = Readonly<
       readonly durationMs: number | null;
       readonly visibility: CheckVisibility;
       readonly messages: readonly CheckMessage[];
+      readonly records: readonly CoreRecord[];
     }
   | {
       readonly kind: "final";
@@ -57,9 +65,12 @@ const SYSTEM_PROGRESS_CLOCK: ProgressClock = Object.freeze({ now: () => performa
 /** Product-private lifecycle presentation with one owner for feedback and its writer. */
 export function createProgressRenderer(
   writer: ProgressWriter,
-  clock: ProgressClock = SYSTEM_PROGRESS_CLOCK
+  clock: ProgressClock = SYSTEM_PROGRESS_CLOCK,
+  progressRendering: ResolvedProgressRenderingOutput = resolveProgressRenderingOutput({
+    enabled: true
+  })
 ): ProgressRenderer {
-  const controller = new ProgressRendererController(writer, clock);
+  const controller = new ProgressRendererController(writer, clock, progressRendering);
   return Object.freeze({
     refreshesRunningRegion: controller.refreshesRunningRegion,
     refresh: (): void => controller.refresh(),

package/src/project-run/project-context.ts

@@ -1,11 +1,12 @@
 import type { CheckProjectContext } from "../check/check.ts";
 import type { RunControls } from "./controls/contract.ts";
+import type { ResolvedInvocationPaths } from "./invocation/paths.ts";
 /** Materializes only invocation-wide callback input; Check-local options own domain configuration. */
 export function createProjectContext(
-  input: Readonly<{ readonly controls: RunControls; readonly root: string }>
+  input: Readonly<{ readonly controls: RunControls; readonly paths: ResolvedInvocationPaths }>
 ): CheckProjectContext {
   return Object.freeze({
     flags: Object.freeze([...(input.controls.flags ?? [])]),
-    root: input.root
+    root: input.paths.projectRoot
   });
 }

package/src/project-run/result.ts

@@ -6,79 +6,123 @@ import type { RunControlDiagnostic } from "./controls/validation-result.ts";
 import type { CheckAggregate, RunControls } from "./controls/contract.ts";
 import type { CheckMessageLevel } from "../check/check.ts";
 import type { CoreSnapshot } from "../check-settlement/facts.ts";
-import type { RunOutputStatuses } from "./output-status.ts";
+import type { RunOutputStatuses } from "./outputs/status.ts";
+
+/** Product 不能形成正常 Run 结果时的稳定 invocation diagnostic。 */
 export type RunDiagnostic = Readonly<{
-  readonly code: "task-graph-invalid" | "task-engine-failed" | "publication-model-failed";
+  /** 失败的 Run-owned execution 或 planning boundary；它不是任何 Check 的 terminal status。 */
+  readonly code:
+    | "admission-policy-failed"
+    | "admission-strategy-preparation-failed"
+    | "task-graph-invalid"
+    | "task-engine-failed"
+    | "publication-model-failed";
 }>;
+
+/** 一项 executable Check 的最终 duration readback。 */
 export type CheckDuration = Readonly<{
+  /** 与 snapshot 中 Check facts 相同的 stable Check identity。 */
   readonly checkId: string;
+  /** 已测量的 execution duration；未进入 execution 的 Check 为 `null`，不是零时长。 */
   readonly durationMs: number | null;
 }>;
+
+/** Run 在 Check terminal lifecycle 中接受的人读 message。 */
 export interface CheckRunMessage {
+  /** 产生 message 的 stable Check identity。 */
   readonly checkId: string;
+  /** author message 或已捕获 console output 的 presentation severity。 */
   readonly level: CheckMessageLevel;
+  /** owning Check 或 Product capture 使用的稳定 message code。 */
   readonly code: string;
+  /** 人读正文；不能代替 snapshot 中的 terminal outcome。 */
   readonly message: string;
 }
+
+/** 只有已形成 terminal Check facts 的 Run branch 才具备的完整结果 readback。 */
 export interface RunResultFacts {
+  /** 调用方未配置 aggregation 时为 `null`；否则是选中 Check statuses 的 invocation-level conclusion。 */
   readonly aggregate: CheckAggregate | null;
+  /** 按 canonical Check order 的 duration facts；未执行 Check 仍以 `null` 保留。 */
   readonly checkDurations: readonly CheckDuration[];
+  /** 已接受的 author 与 console-capture messages，不决定 Check outcome。 */
   readonly checkMessages: readonly CheckRunMessage[];
+  /** 已结算的完整 Check 与 supplemental Record facts。 */
   readonly snapshot: CoreSnapshot;
 }
 /** 一次 Project Run 的可判别结果；output failure 保留已结算 facts。 */
 export type RunResult = Readonly<
   | {
+      /** Definition、RunControls 或 aggregation selection 无效；没有执行任何 Check author callback。 */
       readonly kind: "configuration";
+      /** Definition normalization 时仍可报告、但不单独阻止本 branch 的 warning。 */
       readonly definitionWarnings: readonly DefinitionWarning[];
+      /** 指向被拒绝 Definition 或 RunControls value 的 closed diagnostic。 */
       readonly diagnostic: ProjectDefinitionDiagnostic | RunControlDiagnostic;
     }
   | {
+      /** 配置有效，但 static Check graph 不能进入 execution planning。 */
       readonly kind: "planning";
+      /** normalized declarative Definition 的 matching signal；不包含 RunControls 或 outcome。 */
       readonly declarativeFingerprint: string;
       readonly definitionWarnings: readonly DefinitionWarning[];
+      /** 这次 planning 失败的 Product diagnostic。 */
       readonly diagnostic: RunDiagnostic;
+      /** 配置有效后各 terminal output participant 的独立状态。 */
       readonly outputs: RunOutputStatuses;
     }
   | {
+      /** invocation 在 Check work 开始前或 planning 中响应 caller cancellation。 */
       readonly kind: "cancelled";
       readonly declarativeFingerprint: string;
       readonly definitionWarnings: readonly DefinitionWarning[];
       readonly outputs: RunOutputStatuses;
+      /** 取消发生在尚未形成 terminal Check facts 的阶段。 */
       readonly phase: "pre-work" | "planning";
     }
   | {
+      /** invocation 在至少可能已开始 Check work 的 execution 阶段响应 caller cancellation。 */
       readonly kind: "cancelled";
       readonly declarativeFingerprint: string;
       readonly definitionWarnings: readonly DefinitionWarning[];
       readonly outputs: RunOutputStatuses;
+      /** 此 branch 总在 terminal Check facts 形成后的 execution cancellation 返回。 */
       readonly phase: "execution";
+      /** 按 canonical Check order 的 duration facts；未执行 Check 为 `null`。 */
       readonly checkDurations: readonly CheckDuration[];
+      /** cancellation 前已接受的 author 与 console-capture messages。 */
       readonly checkMessages: readonly CheckRunMessage[];
+      /** cancellation 时已结算的完整 Check 与 supplemental Record facts。 */
       readonly snapshot: CoreSnapshot;
     }
   | ({
+      /** 所有 Check 已完成 terminal settlement；不表示每项 Check 都 `passed`。 */
       readonly kind: "completed";
       readonly declarativeFingerprint: string;
       readonly definitionWarnings: readonly DefinitionWarning[];
       readonly outputs: RunOutputStatuses;
     } & RunResultFacts)
   | {
+      /** Product execution/settlement infrastructure 失败；不把它误表示为 Check `failed`。 */
       readonly kind: "execution";
       readonly declarativeFingerprint: string;
       readonly definitionWarnings: readonly DefinitionWarning[];
+      /** 停止正常 execution 的 Product diagnostic；本 branch 不提供 partial snapshot。 */
       readonly diagnostic: RunDiagnostic;
       readonly outputs: RunOutputStatuses;
     }
   | ({
+      /** Check facts 已完整结算，但至少一个 terminal output participant 失败。 */
       readonly kind: "output";
       readonly declarativeFingerprint: string;
       readonly definitionWarnings: readonly DefinitionWarning[];
+      /** 失败的 machine、progress、diagnostic 或 scheduler-measurement output 类别。 */
       readonly diagnostic: Readonly<{
         readonly code:
           | "machine-publication-failed"
           | "progress-rendering-failed"
-          | "diagnostic-logging-failed";
+          | "diagnostic-logging-failed"
+          | "scheduler-measurement-hooks-failed";
       }>;
       readonly outputs: RunOutputStatuses;
     } & RunResultFacts)
@@ -115,6 +159,8 @@ function outputDiagnosticCode(
       return "progress-rendering-failed";
     case "diagnosticLogging":
       return "diagnostic-logging-failed";
+    case "measurementHooks":
+      return "scheduler-measurement-hooks-failed";
   }
 }
 

package/src/project-run/run.ts

@@ -2,22 +2,23 @@ import type { ProjectDefinition } from "../project-definition/project-definition
 import type { RunControls } from "./controls/contract.ts";
 import { validateProjectDefinition } from "../project-definition/project-definition-validation.ts";
 import { validateRunControls } from "./controls/validation.ts";
-import { executeValidatedRun } from "./invocation.ts";
+import { executeValidatedRun } from "./invocation/run.ts";
 import type { RunResult } from "./result.ts";
 
-export type { RunOutputStatus, RunOutputStatuses } from "./output-status.ts";
+export type { RunOutputStatus, RunOutputStatuses } from "./outputs/status.ts";
 export type { RunDiagnostic, RunResult } from "./result.ts";
 
 /**
- * 在调用方的 Bun runtime 中执行一个由项目拥有的 Project Definition。
+ * 在调用方的 Node runtime 中执行一个由项目拥有的 Project Definition。
  *
  * @param definition - Project Definition input；{@link defineConfig} 补齐 defaults，run 在 invocation 前验证。
  * @param controls - 本次 invocation context 与 outputs 使用的闭合控制值。
  * @returns ordinary configuration、planning、execution、cancellation 与 output failures 通过 `RunResult`
  * 返回；调用方先按 `kind` narrow。
- * @remarks Definition validation 关闭 authoring grammar；可选 Check preflight 组成 invocation execution barrier，
- * 并在 execution callback、dependency resolver 或 scanner 前完成。`output` branch 同时提供完整 final
- * snapshot 与 output failure diagnostic。
+ * @remarks Definition validation 关闭 authoring grammar；可选 Check preflight 在其 Task 通过直接 relation
+ * readiness 后被 Scheduler admission 时运行，并先于该 Check 自己的 execution callback。它受该 Task 的
+ * mutex、capacity、priority 与 cancellation 约束，而不是 invocation-wide barrier。`output` branch 同时提供
+ * 完整 final snapshot 与 output failure diagnostic。
  */
 export async function run(
   definition: ProjectDefinition,