@zxyycom/vibe-check 0.0.1

package/dist/esm/project-run/task-scheduler/scheduler-decision-model.mjs

@@ -0,0 +1,45 @@
+export function reservationUnchanged() {
+    return Object.freeze({ kind: "unchanged" });
+}
+export function reservationSet(taskId) {
+    return Object.freeze({ kind: "set", taskId });
+}
+export function reservationClear() {
+    return Object.freeze({ kind: "clear" });
+}
+export function freezeDecision(decision) {
+    const trigger = freezeTrigger(decision.trigger);
+    switch (decision.kind) {
+        case "admit":
+        case "await-running":
+            return Object.freeze({ ...decision, trigger });
+        case "settle-blocked":
+            return Object.freeze({
+                ...decision,
+                dependencyIds: Object.freeze([...decision.dependencyIds]),
+                trigger
+            });
+        case "cancel-pending":
+            return Object.freeze({ ...decision, taskIds: Object.freeze([...decision.taskIds]), trigger });
+        case "complete":
+            return Object.freeze({ ...decision, trigger });
+    }
+}
+function freezeTrigger(trigger) {
+    switch (trigger.kind) {
+        case "execution-started":
+        case "admission-continued":
+        case "cancellation-observed":
+        case "cancellation-applied":
+            return Object.freeze({ kind: trigger.kind });
+        case "blocked-settled":
+            return Object.freeze({ kind: trigger.kind, taskId: trigger.taskId });
+        case "task-settled":
+            return Object.freeze({
+                kind: trigger.kind,
+                settlementKind: trigger.settlementKind,
+                taskId: trigger.taskId
+            });
+    }
+}
+//# sourceMappingURL=scheduler-decision-model.mjs.map

package/dist/esm/project-run/task-scheduler/scheduler-decision-model.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-decision-model.mjs","sourceRoot":"","sources":["../../../../src/project-run/task-scheduler/scheduler-decision-model.ts"],"names":[],"mappings":"AA8GA,MAAM,UAAU,oBAAoB;IAClC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAA2B;IACxD,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChD,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,OAAO,CAAC;QACb,KAAK,eAAe;YAClB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QACjD,KAAK,gBAAgB;YACnB,OAAO,MAAM,CAAC,MAAM,CAAC;gBACnB,GAAG,QAAQ;gBACX,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;gBACzD,OAAO;aACR,CAAC,CAAC;QACL,KAAK,gBAAgB;YACnB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAChG,KAAK,UAAU;YACb,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,OAAyB;IAC9C,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,mBAAmB,CAAC;QACzB,KAAK,qBAAqB,CAAC;QAC3B,KAAK,uBAAuB,CAAC;QAC7B,KAAK,sBAAsB;YACzB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/C,KAAK,iBAAiB;YACpB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvE,KAAK,cAAc;YACjB,OAAO,MAAM,CAAC,MAAM,CAAC;gBACnB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;IACP,CAAC;AACH,CAAC","sourcesContent":["import type { PlannedTaskGraph } from \"./graph.ts\";\n\nexport type SchedulerSettlementKind = \"completed\" | \"failed\" | \"blocked\" | \"cancelled-before-start\";\n\nexport type SchedulerTrigger =\n  | Readonly<{ readonly kind: \"execution-started\" }>\n  | Readonly<{ readonly kind: \"admission-continued\" }>\n  | Readonly<{ readonly kind: \"blocked-settled\"; readonly taskId: string }>\n  | Readonly<{\n      readonly kind: \"task-settled\";\n      readonly settlementKind: SchedulerSettlementKind;\n      readonly taskId: string;\n    }>\n  | Readonly<{ readonly kind: \"cancellation-observed\" }>\n  | Readonly<{ readonly kind: \"cancellation-applied\" }>;\n\nexport interface SchedulerSnapshot {\n  readonly graph: PlannedTaskGraph;\n  readonly isAbortRequested: boolean;\n  readonly isCancelled: boolean;\n  readonly pendingTaskIds: readonly string[];\n  readonly reservationTaskId: string | undefined;\n  readonly runningMutexes: readonly string[];\n  readonly runningTaskIds: readonly string[];\n  readonly settledTasks: readonly Readonly<{\n    readonly kind: SchedulerSettlementKind;\n    readonly taskId: string;\n  }>[];\n  readonly activeScopeIds: readonly string[];\n  readonly maxParallel: number;\n}\n\nexport interface SchedulerCapacity {\n  readonly effectiveMaxParallel: number;\n  readonly maxParallel: number;\n  readonly running: number;\n}\n\nexport interface SchedulerBlockerSummary {\n  readonly dependency: number;\n  readonly mutex: number;\n  readonly rootCapacity: boolean;\n  readonly scopeCapacity: boolean;\n}\n\nexport interface SchedulerReservationContext {\n  readonly taskId: string | null;\n}\n\nexport interface SchedulerDecisionContext {\n  readonly blockers: SchedulerBlockerSummary;\n  readonly capacity: SchedulerCapacity;\n  readonly reservation: SchedulerReservationContext;\n}\n\nexport type ReservationUpdate =\n  | Readonly<{ readonly kind: \"unchanged\" }>\n  | Readonly<{ readonly kind: \"set\"; readonly taskId: string }>\n  | Readonly<{ readonly kind: \"clear\" }>;\n\nexport type SchedulerAdmissionReason =\n  | \"reservation\"\n  | \"tightening-scope\"\n  | \"constrained-continuation\"\n  | \"canonical-order\";\n\nexport type SchedulerAwaitReason =\n  | \"cancellation-drain\"\n  | \"dependency-or-mutex\"\n  | \"running-drain\"\n  | \"root-capacity\"\n  | \"active-scope-capacity\"\n  | \"reserved-tightening-scope\";\n\nexport type SchedulerDecision = SchedulerDecisionContext &\n  (\n    | Readonly<{\n        readonly eligibleCount: number;\n        readonly kind: \"admit\";\n        readonly reason: SchedulerAdmissionReason;\n        readonly reservationUpdate: ReservationUpdate;\n        readonly scopeToActivate: string | null;\n        readonly taskId: string;\n        readonly trigger: SchedulerTrigger;\n      }>\n    | Readonly<{\n        readonly dependencyIds: readonly string[];\n        readonly kind: \"settle-blocked\";\n        readonly taskId: string;\n        readonly trigger: SchedulerTrigger;\n      }>\n    | Readonly<{\n        readonly eligibleCount: number;\n        readonly kind: \"await-running\";\n        readonly reason: SchedulerAwaitReason;\n        readonly reservationUpdate: ReservationUpdate;\n        readonly trigger: SchedulerTrigger;\n      }>\n    | Readonly<{\n        readonly kind: \"cancel-pending\";\n        readonly taskIds: readonly string[];\n        readonly trigger: SchedulerTrigger;\n      }>\n    | Readonly<{\n        readonly cancelled: boolean;\n        readonly kind: \"complete\";\n        readonly trigger: SchedulerTrigger;\n      }>\n  );\n\nexport function reservationUnchanged(): ReservationUpdate {\n  return Object.freeze({ kind: \"unchanged\" });\n}\n\nexport function reservationSet(taskId: string): ReservationUpdate {\n  return Object.freeze({ kind: \"set\", taskId });\n}\n\nexport function reservationClear(): ReservationUpdate {\n  return Object.freeze({ kind: \"clear\" });\n}\n\nexport function freezeDecision(decision: SchedulerDecision): SchedulerDecision {\n  const trigger = freezeTrigger(decision.trigger);\n  switch (decision.kind) {\n    case \"admit\":\n    case \"await-running\":\n      return Object.freeze({ ...decision, trigger });\n    case \"settle-blocked\":\n      return Object.freeze({\n        ...decision,\n        dependencyIds: Object.freeze([...decision.dependencyIds]),\n        trigger\n      });\n    case \"cancel-pending\":\n      return Object.freeze({ ...decision, taskIds: Object.freeze([...decision.taskIds]), trigger });\n    case \"complete\":\n      return Object.freeze({ ...decision, trigger });\n  }\n}\n\nfunction freezeTrigger(trigger: SchedulerTrigger): SchedulerTrigger {\n  switch (trigger.kind) {\n    case \"execution-started\":\n    case \"admission-continued\":\n    case \"cancellation-observed\":\n    case \"cancellation-applied\":\n      return Object.freeze({ kind: trigger.kind });\n    case \"blocked-settled\":\n      return Object.freeze({ kind: trigger.kind, taskId: trigger.taskId });\n    case \"task-settled\":\n      return Object.freeze({\n        kind: trigger.kind,\n        settlementKind: trigger.settlementKind,\n        taskId: trigger.taskId\n      });\n  }\n}\n"]}

package/dist/esm/project-run/task-scheduler/scheduler-decision.mjs

@@ -0,0 +1,74 @@
+import { decideAdmission } from "./scheduler-admission-decision.mjs";
+import { decisionContext, inspectSnapshot, selectBlockedTask } from "./scheduler-decision-inspection.mjs";
+import { freezeDecision, reservationUnchanged } from "./scheduler-decision-model.mjs";
+/**
+ * Computes the next generic task-engine action from an immutable state projection.
+ * Starting work, awaiting promises, cancellation, and diagnostic output remain in
+ * the imperative scheduler shell.
+ */
+export function decideScheduler(snapshot, trigger) {
+    const state = inspectSnapshot(snapshot);
+    const cycle = Object.freeze({
+        context: decisionContext(state),
+        state,
+        trigger
+    });
+    const terminalDecision = decideTerminalSchedulerAction(cycle, snapshot);
+    if (terminalDecision !== undefined)
+        return terminalDecision;
+    const blocked = selectBlockedTask(state);
+    if (blocked !== undefined) {
+        return freezeDecision({
+            ...cycle.context,
+            dependencyIds: blocked.dependencyIds,
+            kind: "settle-blocked",
+            taskId: blocked.task.id,
+            trigger
+        });
+    }
+    return decideAdmission(cycle);
+}
+function decideTerminalSchedulerAction(cycle, snapshot) {
+    if (cycle.state.pendingTasks.length === 0 && cycle.state.runningTaskIds.size === 0) {
+        return freezeDecision({
+            ...cycle.context,
+            cancelled: snapshot.isCancelled,
+            kind: "complete",
+            trigger: cycle.trigger
+        });
+    }
+    if (snapshot.isAbortRequested && !snapshot.isCancelled) {
+        return freezeDecision({
+            ...cycle.context,
+            kind: "cancel-pending",
+            taskIds: snapshot.pendingTaskIds,
+            trigger: Object.freeze({ kind: "cancellation-observed" })
+        });
+    }
+    if (snapshot.isCancelled) {
+        if (cycle.state.pendingTasks.length > 0) {
+            throw new Error("cancelled scheduler state retains pending tasks");
+        }
+        return cancellationDrainDecision(cycle);
+    }
+    if (cycle.state.pendingTasks.length === 0)
+        return runningDrainDecision(cycle);
+    return undefined;
+}
+function cancellationDrainDecision(cycle) {
+    return awaitDrainDecision(cycle, "cancellation-drain");
+}
+function runningDrainDecision(cycle) {
+    return awaitDrainDecision(cycle, "running-drain");
+}
+function awaitDrainDecision(cycle, reason) {
+    return freezeDecision({
+        ...cycle.context,
+        eligibleCount: 0,
+        kind: "await-running",
+        reason,
+        reservationUpdate: reservationUnchanged(),
+        trigger: cycle.trigger
+    });
+}
+//# sourceMappingURL=scheduler-decision.mjs.map

package/dist/esm/project-run/task-scheduler/scheduler-decision.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-decision.mjs","sourceRoot":"","sources":["../../../../src/project-run/task-scheduler/scheduler-decision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA+B,MAAM,mCAAmC,CAAC;AACjG,OAAO,EACL,eAAe,EACf,eAAe,EACf,iBAAiB,EAClB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAcrF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,QAA2B,EAC3B,OAAyB;IAEzB,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,KAAK,GAA2B,MAAM,CAAC,MAAM,CAAC;QAClD,OAAO,EAAE,eAAe,CAAC,KAAK,CAAC;QAC/B,KAAK;QACL,OAAO;KACR,CAAC,CAAC;IACH,MAAM,gBAAgB,GAAG,6BAA6B,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxE,IAAI,gBAAgB,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAC;IAE5D,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,cAAc,CAAC;YACpB,GAAG,KAAK,CAAC,OAAO;YAChB,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,IAAI,EAAE,gBAAgB;YACtB,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE;YACvB,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,6BAA6B,CACpC,KAA6B,EAC7B,QAA2B;IAE3B,IAAI,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACnF,OAAO,cAAc,CAAC;YACpB,GAAG,KAAK,CAAC,OAAO;YAChB,SAAS,EAAE,QAAQ,CAAC,WAAW;YAC/B,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,QAAQ,CAAC,gBAAgB,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACvD,OAAO,cAAc,CAAC;YACpB,GAAG,KAAK,CAAC,OAAO;YAChB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,QAAQ,CAAC,cAAc;YAChC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC9E,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,yBAAyB,CAAC,KAA6B;IAC9D,OAAO,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,oBAAoB,CAAC,KAA6B;IACzD,OAAO,kBAAkB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,kBAAkB,CACzB,KAA6B,EAC7B,MAAgF;IAEhF,OAAO,cAAc,CAAC;QACpB,GAAG,KAAK,CAAC,OAAO;QAChB,aAAa,EAAE,CAAC;QAChB,IAAI,EAAE,eAAe;QACrB,MAAM;QACN,iBAAiB,EAAE,oBAAoB,EAAE;QACzC,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { decideAdmission, type SchedulerDecisionCycle } from \"./scheduler-admission-decision.ts\";\nimport {\n  decisionContext,\n  inspectSnapshot,\n  selectBlockedTask\n} from \"./scheduler-decision-inspection.ts\";\nimport { freezeDecision, reservationUnchanged } from \"./scheduler-decision-model.ts\";\nimport type {\n  SchedulerDecision,\n  SchedulerSnapshot,\n  SchedulerTrigger\n} from \"./scheduler-decision-model.ts\";\n\nexport type {\n  SchedulerDecision,\n  SchedulerSettlementKind,\n  SchedulerSnapshot,\n  SchedulerTrigger\n} from \"./scheduler-decision-model.ts\";\n\n/**\n * Computes the next generic task-engine action from an immutable state projection.\n * Starting work, awaiting promises, cancellation, and diagnostic output remain in\n * the imperative scheduler shell.\n */\nexport function decideScheduler(\n  snapshot: SchedulerSnapshot,\n  trigger: SchedulerTrigger\n): SchedulerDecision {\n  const state = inspectSnapshot(snapshot);\n  const cycle: SchedulerDecisionCycle = Object.freeze({\n    context: decisionContext(state),\n    state,\n    trigger\n  });\n  const terminalDecision = decideTerminalSchedulerAction(cycle, snapshot);\n  if (terminalDecision !== undefined) return terminalDecision;\n\n  const blocked = selectBlockedTask(state);\n  if (blocked !== undefined) {\n    return freezeDecision({\n      ...cycle.context,\n      dependencyIds: blocked.dependencyIds,\n      kind: \"settle-blocked\",\n      taskId: blocked.task.id,\n      trigger\n    });\n  }\n\n  return decideAdmission(cycle);\n}\n\nfunction decideTerminalSchedulerAction(\n  cycle: SchedulerDecisionCycle,\n  snapshot: SchedulerSnapshot\n): SchedulerDecision | undefined {\n  if (cycle.state.pendingTasks.length === 0 && cycle.state.runningTaskIds.size === 0) {\n    return freezeDecision({\n      ...cycle.context,\n      cancelled: snapshot.isCancelled,\n      kind: \"complete\",\n      trigger: cycle.trigger\n    });\n  }\n  if (snapshot.isAbortRequested && !snapshot.isCancelled) {\n    return freezeDecision({\n      ...cycle.context,\n      kind: \"cancel-pending\",\n      taskIds: snapshot.pendingTaskIds,\n      trigger: Object.freeze({ kind: \"cancellation-observed\" })\n    });\n  }\n  if (snapshot.isCancelled) {\n    if (cycle.state.pendingTasks.length > 0) {\n      throw new Error(\"cancelled scheduler state retains pending tasks\");\n    }\n    return cancellationDrainDecision(cycle);\n  }\n  if (cycle.state.pendingTasks.length === 0) return runningDrainDecision(cycle);\n  return undefined;\n}\n\nfunction cancellationDrainDecision(cycle: SchedulerDecisionCycle): SchedulerDecision {\n  return awaitDrainDecision(cycle, \"cancellation-drain\");\n}\n\nfunction runningDrainDecision(cycle: SchedulerDecisionCycle): SchedulerDecision {\n  return awaitDrainDecision(cycle, \"running-drain\");\n}\n\nfunction awaitDrainDecision(\n  cycle: SchedulerDecisionCycle,\n  reason: Extract<SchedulerDecision, { readonly kind: \"await-running\" }>[\"reason\"]\n): SchedulerDecision {\n  return freezeDecision({\n    ...cycle.context,\n    eligibleCount: 0,\n    kind: \"await-running\",\n    reason,\n    reservationUpdate: reservationUnchanged(),\n    trigger: cycle.trigger\n  });\n}\n"]}

package/dist/esm/project-run/task-scheduler/scheduler.mjs

@@ -0,0 +1,147 @@
+import { prepareTaskGraph } from "./graph.mjs";
+import { diagnosticTags } from "../diagnostic-logging/logger.mjs";
+import { decideScheduler } from "./scheduler-decision.mjs";
+import { cancelPendingTasks, createSchedulerState, recordSettlement, snapshotSchedulerState } from "./execution-state.mjs";
+export async function runTaskGraph(options) {
+    const graph = prepareTaskGraph(options.graph, options.maxParallel);
+    const state = createSchedulerState(graph, options);
+    let trigger = Object.freeze({ kind: "execution-started" });
+    while (true) {
+        const decision = decideScheduler(snapshotSchedulerState(state), trigger);
+        observeSchedulerDecision(state, decision);
+        switch (decision.kind) {
+            case "admit":
+                applyAdmission(state, decision);
+                trigger = Object.freeze({ kind: "admission-continued" });
+                continue;
+            case "settle-blocked":
+                applyBlockedSettlement(state, decision);
+                trigger = Object.freeze({ kind: "blocked-settled", taskId: decision.taskId });
+                continue;
+            case "cancel-pending":
+                applyCancellation(state, decision);
+                trigger = Object.freeze({ kind: "cancellation-applied" });
+                continue;
+            case "await-running": {
+                applyReservationUpdate(state, decision.reservationUpdate);
+                const completion = await nextRunningSettlement(state);
+                settleRunningTask(state, completion);
+                trigger = Object.freeze({
+                    kind: "task-settled",
+                    settlementKind: completion.settlement.kind,
+                    taskId: completion.taskId
+                });
+                continue;
+            }
+            case "complete":
+                return buildTaskGraphRun(state);
+        }
+    }
+}
+function observeSchedulerDecision(state, decision) {
+    state.diagnosticLogger?.observe({
+        event: "scheduler.decision",
+        tags: schedulerDecisionTags(decision),
+        details: decision
+    });
+}
+function schedulerDecisionTags(decision) {
+    return diagnosticTags("SCHEDULER", decision.kind.toUpperCase(), ...("taskId" in decision ? [`TASK:${decision.taskId}`] : []));
+}
+function applyAdmission(state, decision) {
+    const task = takePendingTask(state, decision.taskId, "admission");
+    applyReservationUpdate(state, decision.reservationUpdate);
+    for (const mutex of task.mutex) {
+        state.runningMutexes.add(mutex);
+    }
+    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) => failedTaskCompletion(task.id, error));
+    state.runningById.set(task.id, { task, completion });
+}
+function activateScope(state, scopeId) {
+    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(state, decision) {
+    const task = takePendingTask(state, decision.taskId, "blocked settlement");
+    recordSettlement(state, task, Object.freeze({ kind: "blocked", dependencyIds: decision.dependencyIds }));
+}
+function applyCancellation(state, decision) {
+    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(state, reservation) {
+    switch (reservation.kind) {
+        case "unchanged":
+            return;
+        case "set":
+            state.reservationTaskId = reservation.taskId;
+            return;
+        case "clear":
+            state.reservationTaskId = undefined;
+            return;
+    }
+}
+function takePendingTask(state, taskId, action) {
+    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(state) {
+    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(state, result) {
+    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(taskId, value) {
+    const settlement = { kind: "completed", value };
+    return Object.freeze({ taskId, settlement: Object.freeze(settlement) });
+}
+function failedTaskCompletion(taskId, error) {
+    const settlement = { kind: "failed", error };
+    return Object.freeze({ taskId, settlement: Object.freeze(settlement) });
+}
+function buildTaskGraphRun(state) {
+    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, right) {
+    return left.length === right.length && left.every((taskId, index) => taskId === right[index]);
+}
+//# sourceMappingURL=scheduler.mjs.map

package/dist/esm/project-run/task-scheduler/scheduler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.mjs","sourceRoot":"","sources":["../../../../src/project-run/task-scheduler/scheduler.ts"],"names":[],"mappings":"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","sourcesContent":["import { prepareTaskGraph, type PlannedTask } from \"./graph.ts\";\nimport { diagnosticTags } from \"../diagnostic-logging/logger.ts\";\nimport {\n  decideScheduler,\n  type SchedulerDecision,\n  type SchedulerTrigger\n} from \"./scheduler-decision.ts\";\nimport {\n  cancelPendingTasks,\n  createSchedulerState,\n  recordSettlement,\n  snapshotSchedulerState,\n  type RunningTaskCompletion,\n  type RunTaskGraphOptions,\n  type SchedulerState,\n  type TaskGraphRun,\n  type TaskSettlement\n} from \"./execution-state.ts\";\n\nexport type {\n  RunTaskGraphOptions,\n  SettledTask,\n  TaskExecutionContext,\n  TaskGraphRun,\n  TaskSettlement\n} from \"./execution-state.ts\";\n\nexport async function runTaskGraph<TResult>(\n  options: RunTaskGraphOptions<TResult>\n): Promise<TaskGraphRun<TResult>> {\n  const graph = prepareTaskGraph(options.graph, options.maxParallel);\n  const state = createSchedulerState(graph, options);\n  let trigger: SchedulerTrigger = Object.freeze({ kind: \"execution-started\" });\n\n  while (true) {\n    const decision = decideScheduler(snapshotSchedulerState(state), trigger);\n    observeSchedulerDecision(state, decision);\n\n    switch (decision.kind) {\n      case \"admit\":\n        applyAdmission(state, decision);\n        trigger = Object.freeze({ kind: \"admission-continued\" });\n        continue;\n      case \"settle-blocked\":\n        applyBlockedSettlement(state, decision);\n        trigger = Object.freeze({ kind: \"blocked-settled\", taskId: decision.taskId });\n        continue;\n      case \"cancel-pending\":\n        applyCancellation(state, decision);\n        trigger = Object.freeze({ kind: \"cancellation-applied\" });\n        continue;\n      case \"await-running\": {\n        applyReservationUpdate(state, decision.reservationUpdate);\n        const completion = await nextRunningSettlement(state);\n        settleRunningTask(state, completion);\n        trigger = Object.freeze({\n          kind: \"task-settled\",\n          settlementKind: completion.settlement.kind,\n          taskId: completion.taskId\n        });\n        continue;\n      }\n      case \"complete\":\n        return buildTaskGraphRun(state);\n    }\n  }\n}\n\nfunction observeSchedulerDecision<TResult>(\n  state: SchedulerState<TResult>,\n  decision: SchedulerDecision\n): void {\n  state.diagnosticLogger?.observe({\n    event: \"scheduler.decision\",\n    tags: schedulerDecisionTags(decision),\n    details: decision\n  });\n}\n\nfunction schedulerDecisionTags(decision: SchedulerDecision): readonly string[] {\n  return diagnosticTags(\n    \"SCHEDULER\",\n    decision.kind.toUpperCase(),\n    ...(\"taskId\" in decision ? [`TASK:${decision.taskId}`] : [])\n  );\n}\n\nfunction applyAdmission<TResult>(\n  state: SchedulerState<TResult>,\n  decision: Extract<SchedulerDecision, { readonly kind: \"admit\" }>\n): void {\n  const task = takePendingTask(state, decision.taskId, \"admission\");\n  applyReservationUpdate(state, decision.reservationUpdate);\n  for (const mutex of task.mutex) {\n    state.runningMutexes.add(mutex);\n  }\n  activateScope(state, decision.scopeToActivate);\n\n  const completion = Promise.resolve()\n    .then(() => state.execute(task, Object.freeze({ signal: state.signal })))\n    .then((value) => completedTaskCompletion(task.id, value))\n    .catch((error: unknown) => failedTaskCompletion<TResult>(task.id, error));\n  state.runningById.set(task.id, { task, completion });\n}\n\nfunction activateScope<TResult>(state: SchedulerState<TResult>, scopeId: string | null): void {\n  if (scopeId === null) return;\n  const scope = state.scopesById.get(scopeId);\n  if (scope === undefined)\n    throw new Error(`scheduler admission references unknown scope ${scopeId}`);\n  scope.isActive = true;\n}\n\nfunction applyBlockedSettlement<TResult>(\n  state: SchedulerState<TResult>,\n  decision: Extract<SchedulerDecision, { readonly kind: \"settle-blocked\" }>\n): void {\n  const task = takePendingTask(state, decision.taskId, \"blocked settlement\");\n  recordSettlement(\n    state,\n    task,\n    Object.freeze({ kind: \"blocked\", dependencyIds: decision.dependencyIds })\n  );\n}\n\nfunction applyCancellation<TResult>(\n  state: SchedulerState<TResult>,\n  decision: Extract<SchedulerDecision, { readonly kind: \"cancel-pending\" }>\n): void {\n  const pendingTaskIds = state.pending.map((task) => task.id);\n  if (!sameTaskIds(pendingTaskIds, decision.taskIds)) {\n    throw new Error(\"scheduler cancellation decision no longer matches pending tasks\");\n  }\n  if ((state.reservationTaskId ?? null) !== decision.reservation.taskId) {\n    throw new Error(\"scheduler cancellation decision no longer matches reservation state\");\n  }\n  cancelPendingTasks(state);\n}\n\nfunction applyReservationUpdate<TResult>(\n  state: SchedulerState<TResult>,\n  reservation: Extract<\n    SchedulerDecision,\n    { readonly kind: \"admit\" | \"await-running\" }\n  >[\"reservationUpdate\"]\n): void {\n  switch (reservation.kind) {\n    case \"unchanged\":\n      return;\n    case \"set\":\n      state.reservationTaskId = reservation.taskId;\n      return;\n    case \"clear\":\n      state.reservationTaskId = undefined;\n      return;\n  }\n}\n\nfunction takePendingTask<TResult>(\n  state: SchedulerState<TResult>,\n  taskId: string,\n  action: string\n): PlannedTask {\n  const index = state.pending.findIndex((task) => task.id === taskId);\n  if (index < 0) throw new Error(`task ${taskId} is not pending for ${action}`);\n  const [task] = state.pending.splice(index, 1);\n  if (task === undefined) throw new Error(`task ${taskId} disappeared during ${action}`);\n  return task;\n}\n\nasync function nextRunningSettlement<TResult>(\n  state: SchedulerState<TResult>\n): Promise<RunningTaskCompletion<TResult>> {\n  if (state.runningById.size === 0) {\n    throw new Error(\"scheduler cannot await a task when no task is running\");\n  }\n  return Promise.race([...state.runningById.values()].map((running) => running.completion));\n}\n\nfunction settleRunningTask<TResult>(\n  state: SchedulerState<TResult>,\n  result: RunningTaskCompletion<TResult>\n): void {\n  const running = state.runningById.get(result.taskId);\n  if (running === undefined) {\n    throw new Error(`task ${result.taskId} settled without admission`);\n  }\n  state.runningById.delete(result.taskId);\n  for (const mutex of running.task.mutex) {\n    state.runningMutexes.delete(mutex);\n  }\n  recordSettlement(state, running.task, result.settlement);\n}\n\nfunction completedTaskCompletion<TResult>(\n  taskId: string,\n  value: TResult\n): RunningTaskCompletion<TResult> {\n  const settlement: TaskSettlement<TResult> = { kind: \"completed\", value };\n  return Object.freeze({ taskId, settlement: Object.freeze(settlement) });\n}\n\nfunction failedTaskCompletion<TResult>(\n  taskId: string,\n  error: unknown\n): RunningTaskCompletion<TResult> {\n  const settlement: TaskSettlement<TResult> = { kind: \"failed\", error };\n  return Object.freeze({ taskId, settlement: Object.freeze(settlement) });\n}\n\nfunction buildTaskGraphRun<TResult>(state: SchedulerState<TResult>): TaskGraphRun<TResult> {\n  return Object.freeze({\n    cancelled: state.isCancelled,\n    settlements: Object.freeze(\n      state.graph.tasks.map((task) => {\n        const settlement = state.settlementsByTaskId.get(task.id);\n        if (settlement === undefined) {\n          throw new Error(`task ${task.id} was not settled`);\n        }\n        return Object.freeze({ task, settlement });\n      })\n    )\n  });\n}\n\nfunction sameTaskIds(left: readonly string[], right: readonly string[]): boolean {\n  return left.length === right.length && left.every((taskId, index) => taskId === right[index]);\n}\n"]}

package/docs/api-mechanics.md

@@ -0,0 +1,205 @@
+# 深入理解 Vibe Check API 机制
+
+本文说明 package 的通用 invocation lifecycle：自定义 Check 如何经过 Definition validation、options preflight、execution 与 settlement，以及一次 Run 如何形成 dependency data、aggregation、outputs 和可判别结果。首次集成先阅读[package README](../README.md)；随包 Check 的 options、业务效果和安全边界由各自指南说明；单个 public 字段与函数签名以 installed declarations 为准。
+
+## 一次 Run 的生命周期
+
+以下顺序描述责任与数据流；箭头表示当前阶段成功形成下一阶段的输入：
+
+    ordinary Check values
+      │ defineConfig: fill Definition defaults
+      ▼
+    Project Definition
+      │ run: validate Definition + RunControls, then normalize the Check tree
+      ▼
+    declarative snapshot + fingerprint + complete static graph validation
+      │ sequential all-Check preflight barrier
+      ▼
+    prepared Checks / blocked unavailable outcomes
+      │ build the ready task graph; apply dependency, mutex and parallel scheduling
+      ▼
+    author execution + terminal settlement
+      ▼
+    snapshot + messages + durations
+      │ optional aggregation + enabled output completion
+      ▼
+    RunResult
+
+Run 在 preflight 前验证包含全部可执行 Check 的静态 task graph；完整 barrier 结束后，blocked Check 先结算为
+`unavailable`，其余 prepared Checks 再形成 ready task graph。Run snapshot 保存 Check facts；progress rendering 呈现
+execution lifecycle；machine publication 在 terminal snapshot 形成后写入 machine files。所有 author execution 都在完整
+preflight barrier 之后开始，optional aggregate 也在 terminal facts 结算后计算。
+
+## Definition 与 invocation 的责任
+
+- `defineCheck(value)` 保留 literal `checkId`、options 和 typed-provider parser 的 TypeScript inference。它与同 shape 普通 Check object 具有相同 runtime 语义。
+- `defineConfig(value)` 形成带默认 `apiVersion`、outputs 和 scheduler policy 的 Project Definition。
+- `run(definition, controls?)` 拥有 invocation validation 与 normalization：它关闭递归 Check grammar，detach / canonicalize authored options，并形成 declarative snapshot 与 fingerprint。
+
+fingerprint 使用 normalized declarative fields；preflight 与 execution callbacks 保持为执行行为。同一份 Definition 可以重复调用，每次 Run 都从 authored input 派生自己的 project context、prepared options、terminal facts 和 output statuses。
+
+## options preflight 与 execution
+
+可执行 Check 可以提供 `preflight(options, signal)`，在 author execution 前准备本次 invocation 使用的 options。authored 与 prepared options 同形时可以直接使用 authored options；两种 shape 不同时，TypeScript 要求提供 preflight。
+
+preflight 返回以下三种 closed result 之一：
+
+| 结果 | execution 输入与 Check outcome |
+| --- | --- |
+| `{ status: "success", preparedOptions, messages? }` | 使用 `preparedOptions` 进入 execution。 |
+| `{ status: "failure", action: "block", reason, messages? }` | owning Check 以 `unavailable` 结算。 |
+| `{ status: "failure", action: "continue", reason, fallback, messages? }` | 使用 `fallback` 进入 execution。 |
+
+Run 按 Definition 顺序执行所有 Check 的 preflight，完整 barrier 结束后才启动 Check scheduler。preflight throw、malformed result 或 noncanonical prepared value 把 owning Check 结算为 `unavailable`。prepared options 与 fallback 都会成为 detached、deep-frozen 的 invocation-local value；preflight messages 与后续 terminal outcome 共同呈现 preparation 结果。
+
+Package root 的 `defaultProjectFileSelection` 只是 file-selecting constructor 共用的可组合、深冻结 baseline；spread 该
+value 不会建立跨 Check global config。部分 constructor 原样物化它，具有更窄文件类型能力的 constructor 从相同
+source/exclude 派生精准默认 include；显式 `include` / `exclude` 数组始终由 owning Check 视为完整替换。每项实际默认与
+selected-but-rejected 行为由对应 Check 指南说明。
+
+## terminal result、Records 与 messages
+
+每个可执行 Check 返回一个 terminal result：`passed` / `failed` 带 Check-owned object final data；`not-applicable` / `unavailable` 以 reason 表示本次调用的数据边界。settlement 会 detach、canonicalize 并关闭 final data；callback throw、malformed result 或 noncanonical data 对应 `unavailable` outcome。
+
+`records.report({ id }, data)` 在 owning Check namespace 内追加 supplemental Record。每个 `id` 非空且在该 Check 内唯一，Record data 使用 canonical JSON object；无效或重复 Record 把 owning Check 结算为 `unavailable`。settlement 保留此前已经接受的 Records。
+
+`messages?` 是 owning Check 可选的有序人读说明；consumer 必须先按 outcome 处理事实，不能用 message presence 推断状态。final data、Records 和 messages 分别承载主要事实、补充事实和人读说明。随包 Check 的额外 message 保证由各自指南说明。
+
+## Finding waiver reconciliation
+
+`reconcileFindingWaivers({ findings, identify, waivers })` 是 package root 提供的独立 helper，供 custom Check 或其它
+finding producer 在**完整** finding 候选集合形成后对账。`identify(finding)` 对输入顺序中的每个原 finding 接收完整
+finding；调用方自行选择稳定的语义 identity，例如 path、function name 和 metric 的组合。`identify` 的结果与
+`waiver.identity` 都必须可安全 materialize 为 canonical JSON，helper 按 canonical JSON 的结构而非对象引用匹配。
+
+每项 waiver 的 identity 必须唯一且 reason 为非空 string。重复 canonical identity、无法 canonicalize 的 finding 或
+waiver identity、无效 reason，或 malformed / hostile waiver authoring 都抛出 `TypeError`。每个 configured waiver 都在完整
+集合上获得 audit：`0` 次匹配是 `unused`，`1` 次是 `applied`，`>1` 次是 `overmatched`；过宽 waiver 不会豁免任一 finding。
+
+输出 `findings` 保持输入顺序，并在每项结果中保留同一个原 finding reference。applied waiver 附带的 evidence 是 detached、
+deep-frozen 的 canonical materialization，因此调用方之后修改 authored identity 或 reason 不会改变结果。helper 只返回
+finding disposition 和 waiver audit；它不发布 Record、message 或 terminal outcome。采用它的 Check 自己决定如何发布证据及
+如何结算 actionable finding。
+
+## 递归组合与继承
+
+带 `execution` 的节点形成自己的 outcome；没有 `execution` 的节点只组织子 Check 和 scheduling scope。普通对象字段表示显式 replacement；`inherit({ add, remove })` 只用于在父 `dependsOn` 或 `mutex` collection 上增删。解析后，每个可执行节点拥有自己的 effective options、dependencies、mutexes、visibility 与 parallel budget。
+
+## 类型化依赖数据
+
+producer 同时声明 `execution` 与 `parseData`，从而拥有 final-data contract。consumer 先声明 direct `dependsOn`，再用非泛型 `dependencies.get(checkId)` 读取 canonical data、收窄 `ok`，最后调用 producer 的 parser。
+
+### 完整运行示例
+
+```ts
+import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+const CHANGED_FILES_DATA_VERSION = 1 as const;
+
+type ChangedFilesData = Readonly<{
+  readonly files: readonly string[];
+  readonly version: typeof CHANGED_FILES_DATA_VERSION;
+}>;
+
+const changedFiles = defineCheck({
+  checkId: "changed-files",
+  displayName: "Changed files",
+  parseData(data): ChangedFilesData {
+    if (
+      data.version !== CHANGED_FILES_DATA_VERSION ||
+      !Array.isArray(data.files) ||
+      !data.files.every((value): value is string => typeof value === "string")
+    ) {
+      throw new TypeError("Unsupported changed-files data");
+    }
+    return { files: data.files, version: data.version };
+  },
+  execution() {
+    return {
+      status: "passed",
+      data: { files: ["src/index.ts"], version: CHANGED_FILES_DATA_VERSION }
+    };
+  }
+});
+
+const analyzeChangedFiles = defineCheck({
+  checkId: "analyze-changed-files",
+  displayName: "Analyze changed files",
+  dependsOn: [changedFiles.checkId],
+  execution({ dependencies }) {
+    const read = dependencies.get(changedFiles.checkId);
+    if (!read.ok) return { status: "unavailable", reason: { code: read.error.code } };
+
+    const data = changedFiles.parseData(read.data);
+    return { status: read.status, data: { analyzedFileCount: data.files.length } };
+  }
+});
+
+const definition = defineConfig({
+  checks: [changedFiles, analyzeChangedFiles],
+  outputs: {
+    diagnosticLogging: { enabled: false },
+    machinePublication: { enabled: false },
+    progressRendering: { enabled: false }
+  }
+});
+
+const result = await run(definition);
+if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+```
+
+dependency reader 为已声明且具有 `passed` / `failed` final data 的 direct dependency 返回 `ok: true`，并保留 upstream status；其它读取返回包含原因的 `ok: false`。producer parser 负责 shape、invariant 和 compatibility validation，consumer 显式调用它恢复 provider data。七个随包 Check 都提供 `parseData` 和同实现的 package-root parser；名称与类型见各自指南。
+
+## RunControls 与 Check aggregation
+
+`RunControls` 只作用于一次 `run(definition, controls)`：
+
+- `projectRoot` 决定项目相对路径的解析根。
+- `flags` 成为 callback 可读的 normalized project context。
+- `signal` 供 preflight 与 execution 协作取消；取消结果记录对应 phase。
+- `outputs` 覆盖本次 diagnostic logging、machine publication 或 progress rendering。
+- `checkAggregation` 选择 `checks`，并以 `all` / `any`、`unavailable`、`notApplicable` 与 `empty` policy 形成 invocation aggregate。
+
+aggregation 是 terminal outcomes 之外的 invocation-level fact。它在完整 terminal facts 结算后产生 `passed`、`failed`、`not-applicable` 或 `unavailable`；未配置 policy 时 `aggregate` 为 `null`。consumer 需要调用级结论时显式选择 policy，同时保留每项 Check outcome。
+
+Check-specific invocation facts 由 owning Check 的 options 或 producing Check 的 final data 承载。多个 Checks 共享同一事实时，producer 负责 acquisition policy 与 data shape，下游通过 direct `dependsOn` 读取；上面的 typed dependency 示例聚焦这条 data handoff。
+
+## outputs 与 RunResult 边界
+
+Definition outputs 提供 diagnostic logging、machine publication 与 progress rendering 三项独立 defaults，RunControls 可以只覆盖当前调用需要的部分。configuration 成功后的职责如下：
+
+- 只有 diagnostic logging 或 machine publication 至少一项启用时，Run 才在创建 invocation 阶段捕获一次 immutable wall-clock `startedAtUtc`；两项都禁用时不读取或序列化 wall clock。
+- 启用的 diagnostic logging 在 preflight 前以该 instant 命名 UTC-compact log path，并按事实形成顺序记录 Product core 已知的 invocation、planning、scheduler、handoff 与 output 时间线。每个事件以序号、单调 elapsed、可筛选的 `[]` 标签和 event name 开始；普通事实使用 `key=value`，超出当前主行容量的事实进入有界 continuation line。标签只突出 Run、Check、phase、Scheduler decision 和 outcome 等高频阅读轴；Scheduler decision 的顶层 `kind` / `taskId` 与 Record observation 的顶层 `result` 已由标签完整表达时，不在 facts 中重复。
+- 启用的 machine publication 将同一个 instant 投影为 `run.json` 的 `invocation.timestamp`，所以 timestamp 不是 publication 完成时间；两项同时启用时，日志文件名与 machine timestamp 必须共享该一次捕获。
+- progress rendering 呈现人读 lifecycle。三项 output 都由 Run 调度，并分别返回 status。
+
+这些 diagnostic 行不建立可解析 schema。Run 结束前最后一条可写 diagnostic event 是 `run.terminal-before-log-close`：它只证明 terminal fact 已写入、logger close 尚未确认，随后才尝试关闭日志。
+
+只有 non-configuration `RunResult` 具有有效 output configuration 与 `outputs` readback。此时
+`outputs.diagnosticLogging` 的形状为 `{ enabled, status, file }`，其中 `status` 是
+`"disabled" | "not-run" | "succeeded" | "failed"`；禁用时 `file` 为 `null`，启用时即使文件创建失败也保留预先计算的、
+project-root-relative `run-<UTC 紧凑时间>-<UUID>.log` 目标。无效 Definition、controls 或 aggregation selection 直接返回
+configuration diagnostic，不创建诊断日志。
+
+diagnostic logging 只服务当前人工诊断：它没有 parser、schema/version、跨版本格式兼容、`latest`、retention 或跨 invocation
+discovery contract，也不替代 Check final data、Record、terminal message 或 Check/process adapter 自有的 transcript。logging
+failure 只把该 output 标为 failed，不改写已形成的 Check/Record facts，也不阻断 progress rendering 或 machine publication 的
+闭合。多个 output 都失败时，`RunResult.outputs` 保留每项 status；唯一 `output` diagnostic 依次选择 progress rendering、
+machine publication、diagnostic logging。diagnostic logging 不进入 machine v4；其 machine-field 排除见
+[机器输出契约](output.md)。Check final-data parser 只处理已经取得的单个 data object，不替代该契约。
+
+progress rendering 在 TTY 中维护 running region，在 plain output 与 `TERM=dumb` 中只追加 settled rows。`visibility: "attention"` 只隐藏无 messages 的 passed settled row，不改变 outcome、Records 或 machine output；accepted message 的 code 保留在 `RunResult.checkMessages`，终端只呈现 level 与正文。renderer failure 进入对应 output status，不改写已形成的 Check facts。
+
+按 `RunResult.kind` 和 cancellation phase 读取结果：
+
+| 分支 | 可用 facts 与处理方式 |
+| --- | --- |
+| `completed` | 完整 `snapshot`、`checkDurations`、`checkMessages`、`outputs` 与可选 `aggregate`；继续读取单项 Check outcome。 |
+| `output` | 完整 Check facts 与 output failure diagnostic；消费 facts 并处理失败的 output。 |
+| `cancelled` / `phase: "execution"` | 取消时关闭的 snapshot、durations 与 messages；按 cancellation result 处理。 |
+| `cancelled` / `phase: "pre-work"` 或 `"planning"` | invocation metadata 与 cancellation phase；按 phase 结束调用。 |
+| `configuration` | Definition、controls 或 aggregation selection diagnostic；project callback 执行数为零。 |
+| `planning` | task-graph diagnostic 与 invocation metadata。 |
+| `execution` | Product execution-settlement diagnostic 与 invocation metadata。 |
+
+Check `failed` 是已结算的业务 outcome；Run `execution` 是 invocation infrastructure diagnostic；Run `output` 是完整 Check facts 附带的 diagnostic logging、publication 或 rendering failure diagnostic。