@zxyycom/vibe-check 0.0.2 → 0.0.3

package/src/project-run/check-execution/resolved-checks.ts

@@ -1,72 +1,39 @@
 import type { CheckMessage, CheckProjectContext } from "../../check/check.ts";
 import type {
   NormalizedCheck,
-  SchedulerMeasurementHook
+  SchedulerTerminalEffect
 } from "../../project-definition/project-definition.ts";
 import type { ResourceUnitMapping } from "../../project-definition/resource-unit-mapping.ts";
 import { createCoreCheckSession } from "../../check-settlement/session.ts";
-import {
-  diagnosticTags,
-  summarizeDiagnosticValue,
-  type DiagnosticLogger
-} from "../diagnostic-logging/logger.ts";
-import { prepareTaskGraph } from "../task-scheduler/graph.ts";
+import type { DiagnosticLogger } from "../diagnostic-logging/logger.ts";
 import type { AdmissionSelectionPolicy } from "../task-scheduler/admission-selection-policy.ts";
-import { runTaskGraph } from "../task-scheduler/scheduler.ts";
+import { prepareTaskGraph } from "../task-scheduler/graph.ts";
 import type { SchedulerPerformanceDiagnosticsInput } from "../task-scheduler/measurement/diagnostics.ts";
-import { executeCheckCallback } from "./callback.ts";
-import { artifactDirectoryForCheck, type ResolvedInvocationPaths } from "../invocation/paths.ts";
+import type { ResolvedInvocationPaths } from "../invocation/paths.ts";
 import { runWithCheckConsoleRouter } from "./console-capture.ts";
-import { createCheckDependencies } from "./dependencies.ts";
 import {
-  CheckExecutionInvariantFailure,
   recordSettledCheck,
-  settleCallback,
   type CheckExecutionState,
-  type CheckIdentity,
   type SettledCheckFacts
 } from "./execution-settlement.ts";
-import {
-  checkIdentity,
-  closeResolvedChecks,
-  settleBlockedDependent,
-  trustedFailure
-} from "./execution-finalization.ts";
-import type { CheckExecutionLifecycle } from "./lifecycle.ts";
+import { checkIdentity, closeResolvedChecks } from "./execution-finalization.ts";
+import type { CheckExecutionLifecycle, InvocationLifecycle } from "./lifecycle.ts";
 import { planStaticCheckGraph } from "./plan.ts";
 import {
   selectEffectiveCheckIds,
   resolveFlagControlSettlements,
   type FlagControlSettlement
 } from "./flag-controls.ts";
-import {
-  prepareCheck,
-  type CheckPreflightResolution,
-  type ReadyCheckPreflightResolution
-} from "./preflight.ts";
+import { runScheduledChecks } from "./scheduled-check-run.ts";
+import type { CheckExecutionClock } from "./admitted-check-execution.ts";
 import type { ResolvedCheckExecution } from "./resolved-execution-result.ts";
 
-const INERT_SIGNAL = new AbortController().signal;
 const NO_CHECK_MESSAGES: readonly CheckMessage[] = Object.freeze([]);
-const DIRECT_EXECUTION_INVOCATION_ID = "invocation/v1:direct-check-execution";
-const SYSTEM_MONOTONIC_CLOCK: CheckExecutionClock = Object.freeze({
-  now: () => performance.now()
-});
 
 /** Package-private monotonic clock seam for execution accounting. */
-export type CheckExecutionClock = Readonly<{ now(): number }>;
-
-interface ExecuteCheckInput extends CheckExecutionState {
-  readonly check: NormalizedCheck;
-  readonly clock: CheckExecutionClock;
-  readonly onAdmittedCheck: ((check: NormalizedCheck) => void) | undefined;
-  readonly invocationId: string;
-  readonly paths: ResolvedInvocationPaths | undefined;
-  readonly project: CheckProjectContext;
-  readonly signal: AbortSignal;
-}
+export type { CheckExecutionClock } from "./admitted-check-execution.ts";
 
-type ResolvedCheckExecutionInput = Readonly<{
+export type ResolvedCheckExecutionInput = Readonly<{
   /** Complete prepared private policy handoff; public policy dispatch stays outside execution. */
   readonly admissionPolicy?: AdmissionSelectionPolicy;
   readonly checks: readonly NormalizedCheck[];
@@ -85,10 +52,11 @@ type ResolvedCheckExecutionInput = Readonly<{
   readonly schedulerDiagnosticLogger?: DiagnosticLogger;
   /** Explicit enabled-only diagnostics handoff from the invocation output owner. */
   readonly schedulerPerformanceDiagnostics?: SchedulerPerformanceDiagnosticsInput;
-  readonly schedulerMeasurementHooks?: readonly SchedulerMeasurementHook[];
-  readonly onSchedulerMeasurementHookFailure?: () => void;
-  readonly onSchedulerMeasurementHooksSettled?: () => void;
-  readonly lifecycle?: CheckExecutionLifecycle;
+  readonly schedulerTerminalEffects?: readonly SchedulerTerminalEffect[];
+  readonly onSchedulerTerminalEffectFailure?: () => void;
+  readonly onSchedulerTerminalEffectsSettled?: () => void;
+  readonly checkLifecycle?: CheckExecutionLifecycle;
+  readonly invocationLifecycle?: InvocationLifecycle;
   /** Provider-owned bounded learned admission diagnostics, delivered by invocation. */
   readonly onAdmittedCheck?: (check: NormalizedCheck) => void;
 }>;
@@ -112,76 +80,34 @@ async function executePreparedResolvedChecks(
   const state = createExecutionState({
     checks: input.checks,
     diagnosticLogger: input.diagnosticLogger,
-    lifecycle: input.lifecycle
-  });
-  const flagControlSettlements = resolveFlagControlSettlements({
-    checks: input.checks,
-    diagnosticLogger: input.diagnosticLogger,
-    effectiveCheckIds,
-    signal: input.signal
+    lifecycle: input.checkLifecycle
   });
-  for (const settlement of flagControlSettlements) {
-    settleFlagControlOutcome(state, settlement);
-  }
-  input.lifecycle?.flagControlCompleted();
-  const checksByCheckId = new Map(
-    input.checks.map((check) => [check.definition.checkId, check] as const)
-  );
-  let graphRun: Awaited<ReturnType<typeof runTaskGraph<boolean>>>;
   try {
-    graphRun = await runTaskGraph<boolean>({
-      graph: planStaticCheckGraph(input.checks, input.resourceCapacities),
-      admissionPolicy: input.admissionPolicy,
-      maxParallel: input.maxParallel,
-      diagnosticLogger: input.schedulerDiagnosticLogger ?? input.diagnosticLogger,
-      performanceDiagnostics: input.schedulerPerformanceDiagnostics,
-      measurementHooks: input.schedulerMeasurementHooks,
-      onMeasurementHookFailure: input.onSchedulerMeasurementHookFailure,
-      onMeasurementHooksSettled: input.onSchedulerMeasurementHooksSettled,
-      preAdmissionTaskResults: Object.freeze(
-        flagControlSettlements.map((settlement) =>
-          Object.freeze({
-            taskId: settlement.check.definition.checkId,
-            value: false
-          })
-        )
-      ),
-      signal: input.signal,
-      isPrerequisiteSatisfied: (satisfied) => satisfied,
-      onTaskBlocked: (task, dependencyIds) => {
-        const check = checksByCheckId.get(task.id);
-        if (check === undefined) {
-          throw new CheckExecutionInvariantFailure("Blocked Task has no normalized Check");
-        }
-        settleBlockedDependent({ check, dependencyIds, state });
-      },
-      execute: (task, context) => {
-        const check = checksByCheckId.get(task.id);
-        if (check === undefined) {
-          throw new CheckExecutionInvariantFailure("Task graph has no normalized Check");
-        }
-        return executeAdmittedCheck({
-          ...state,
-          check,
-          clock: input.clock ?? SYSTEM_MONOTONIC_CLOCK,
-          onAdmittedCheck: input.onAdmittedCheck,
-          invocationId: input.invocationId ?? DIRECT_EXECUTION_INVOCATION_ID,
-          paths: input.paths,
-          project: input.project,
-          signal: context.signal ?? INERT_SIGNAL
-        });
-      }
+    const flagControlSettlements = resolveFlagControlSettlements({
+      checks: input.checks,
+      ...(input.diagnosticLogger === undefined ? {} : { diagnosticLogger: input.diagnosticLogger }),
+      effectiveCheckIds,
+      signal: input.signal
+    });
+    for (const settlement of flagControlSettlements) {
+      settleFlagControlOutcome(state, settlement);
+    }
+    input.invocationLifecycle?.selectionSettled();
+    const graphRun = await runScheduledChecks({
+      execution: input,
+      flagControlSettlements,
+      state
     });
-  } catch (error) {
-    throw trustedFailure(error);
-  }
 
-  return closeResolvedChecks({
-    allChecks: input.checks,
-    effectiveCheckIds,
-    graphRun,
-    state
-  });
+    return closeResolvedChecks({
+      allChecks: input.checks,
+      effectiveCheckIds,
+      graphRun,
+      state
+    });
+  } finally {
+    state.handoffsByCheckId.clear();
+  }
 }
 
 function createExecutionState(
@@ -193,6 +119,7 @@ function createExecutionState(
 ): CheckExecutionState {
   return {
     diagnosticLogger: input.diagnosticLogger,
+    handoffsByCheckId: new Map(),
     settledFactsByCheckId: new Map<string, SettledCheckFacts>(),
     lifecycle: input.lifecycle,
     session: createCoreCheckSession(
@@ -216,109 +143,3 @@ function settleFlagControlOutcome(
     state
   });
 }
-
-function settleBlockedPreflight(
-  state: CheckExecutionState,
-  preflight: Extract<CheckPreflightResolution, { readonly kind: "blocked" }>
-): void {
-  const scope = state.session.openCheckScope(preflight.check.definition.checkId);
-  const outcome = scope.settleProduct(preflight.outcome);
-  recordSettledCheck({
-    check: checkIdentity(preflight.check),
-    durationMs: null,
-    messages: preflight.check.preflightMessages,
-    outcome,
-    phase: "preflight",
-    state
-  });
-}
-
-async function executeAdmittedCheck(input: ExecuteCheckInput): Promise<boolean> {
-  observeAdmittedCheck(input);
-  const preflight = await prepareCheck({
-    check: input.check,
-    diagnosticLogger: input.diagnosticLogger,
-    signal: input.signal
-  });
-  if (preflight.kind === "blocked") {
-    settleBlockedPreflight(input, preflight);
-    return false;
-  }
-  return executeReadyCheck({ ...input, preflight });
-}
-
-/** Diagnostic observation belongs to the invocation; it cannot revise admitted Task facts. */
-function observeAdmittedCheck(input: ExecuteCheckInput): void {
-  try {
-    input.onAdmittedCheck?.(input.check);
-  } catch {
-    // Learned diagnostic output is best-effort and has no execution consequence.
-  }
-}
-
-async function executeReadyCheck(
-  input: ExecuteCheckInput & Readonly<{ readonly preflight: ReadyCheckPreflightResolution }>
-): Promise<boolean> {
-  const check = input.preflight.check;
-  const checkId = check.definition.checkId;
-  const scope = input.session.openCheckScope(checkId);
-  const identity = checkIdentity(check);
-  input.diagnosticLogger?.observe({
-    event: "check.started",
-    tags: diagnosticTags(`CHECK:${checkId}`, "EXECUTION", "STARTED"),
-    details: {
-      dependencies: check.dependsOn,
-      displayName: check.definition.displayName,
-      options: summarizeDiagnosticValue(check.options)
-    }
-  });
-  emitStarted(input.lifecycle, identity);
-  const startedAt = input.clock.now();
-  const callback = await executeCheckCallback({
-    artifactDirectory:
-      input.paths === undefined ? null : artifactDirectoryForCheck(input.paths, checkId),
-    check,
-    dependencies: createCheckDependencies({
-      checkId,
-      diagnosticLogger: input.diagnosticLogger,
-      directRelationCheckIds: directRelationCheckIds(check),
-      session: input.session
-    }),
-    diagnosticLogger: input.diagnosticLogger,
-    invocationId: input.invocationId,
-    project: input.project,
-    scope,
-    signal: input.signal
-  });
-  const settled = settleCallback({
-    callback,
-    checkId,
-    diagnosticLogger: input.diagnosticLogger,
-    preflightMessages: check.preflightMessages,
-    scope
-  });
-  recordSettledCheck({
-    check: identity,
-    durationMs: durationSince(startedAt, input.clock),
-    messages: settled.messages,
-    outcome: settled.outcome,
-    phase: "execution",
-    state: input
-  });
-  return settled.outcome.status === "passed";
-}
-
-function directRelationCheckIds(
-  check: Pick<NormalizedCheck, "dependsOn" | "observes">
-): readonly string[] {
-  return Object.freeze([...new Set([...check.dependsOn, ...check.observes])].sort());
-}
-
-function emitStarted(lifecycle: CheckExecutionLifecycle | undefined, check: CheckIdentity): void {
-  lifecycle?.started(Object.freeze({ checkId: check.checkId, displayName: check.displayName }));
-}
-
-function durationSince(startedAt: number, clock: CheckExecutionClock): number {
-  const elapsed = clock.now() - startedAt;
-  return Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : 0;
-}

package/src/project-run/check-execution/scheduled-check-run.ts

@@ -0,0 +1,119 @@
+/** Maps normalized Checks into the Scheduler's opaque Task execute contract. */
+
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { runTaskGraph, type RunTaskGraphOptions } from "../task-scheduler/scheduler.ts";
+import {
+  CheckExecutionInvariantFailure,
+  type CheckExecutionState
+} from "./execution-settlement.ts";
+import { settleBlockedDependent, trustedFailure } from "./execution-finalization.ts";
+import type { FlagControlSettlement } from "./flag-controls.ts";
+import { planStaticCheckGraph } from "./plan.ts";
+import {
+  executeAdmittedCheck,
+  type AdmittedCheckExecutionInput,
+  type CheckExecutionClock
+} from "./admitted-check-execution.ts";
+import type { ResolvedCheckExecutionInput } from "./resolved-checks.ts";
+
+const INERT_SIGNAL = new AbortController().signal;
+const DIRECT_EXECUTION_INVOCATION_ID = "invocation/v1:direct-check-execution";
+const SYSTEM_MONOTONIC_CLOCK: CheckExecutionClock = Object.freeze({
+  now: () => performance.now()
+});
+
+export async function runScheduledChecks(
+  input: Readonly<{
+    readonly execution: ResolvedCheckExecutionInput;
+    readonly flagControlSettlements: readonly FlagControlSettlement[];
+    readonly state: CheckExecutionState;
+  }>
+): Promise<Awaited<ReturnType<typeof runTaskGraph<boolean>>>> {
+  try {
+    return await runTaskGraph(schedulerOptionsFor(input));
+  } catch (error) {
+    throw trustedFailure(error);
+  }
+}
+
+function schedulerOptionsFor(
+  input: Readonly<{
+    readonly execution: ResolvedCheckExecutionInput;
+    readonly flagControlSettlements: readonly FlagControlSettlement[];
+    readonly state: CheckExecutionState;
+  }>
+): RunTaskGraphOptions<boolean> {
+  const execution = input.execution;
+  const checksByCheckId = new Map(
+    execution.checks.map((check) => [check.definition.checkId, check] as const)
+  );
+  const schedulerDiagnosticLogger =
+    execution.schedulerDiagnosticLogger ?? execution.diagnosticLogger;
+  return {
+    graph: planStaticCheckGraph(execution.checks, execution.resourceCapacities),
+    ...(execution.admissionPolicy === undefined
+      ? {}
+      : { admissionPolicy: execution.admissionPolicy }),
+    maxParallel: execution.maxParallel,
+    ...(schedulerDiagnosticLogger === undefined
+      ? {}
+      : { diagnosticLogger: schedulerDiagnosticLogger }),
+    ...(execution.schedulerPerformanceDiagnostics === undefined
+      ? {}
+      : { performanceDiagnostics: execution.schedulerPerformanceDiagnostics }),
+    ...(execution.schedulerTerminalEffects === undefined
+      ? {}
+      : { terminalEffects: execution.schedulerTerminalEffects }),
+    ...(execution.onSchedulerTerminalEffectFailure === undefined
+      ? {}
+      : { onTerminalEffectFailure: execution.onSchedulerTerminalEffectFailure }),
+    ...(execution.onSchedulerTerminalEffectsSettled === undefined
+      ? {}
+      : { onTerminalEffectsSettled: execution.onSchedulerTerminalEffectsSettled }),
+    preAdmissionTaskResults: Object.freeze(
+      input.flagControlSettlements.map((settlement) =>
+        Object.freeze({ taskId: settlement.check.definition.checkId, value: false })
+      )
+    ),
+    ...(execution.signal === undefined ? {} : { signal: execution.signal }),
+    isPrerequisiteSatisfied: (satisfied) => satisfied,
+    onTaskBlocked: (task, dependencyIds) => {
+      settleBlockedDependent({
+        check: requiredNormalizedCheck(checksByCheckId, task, "Blocked Task"),
+        dependencyIds,
+        state: input.state
+      });
+    },
+    execute: (task, context) =>
+      executeAdmittedCheck({
+        ...input.state,
+        ...admittedExecutionFacts(execution),
+        check: requiredNormalizedCheck(checksByCheckId, task, "Task graph"),
+        signal: context.signal ?? INERT_SIGNAL
+      })
+  };
+}
+
+function requiredNormalizedCheck(
+  checksByCheckId: ReadonlyMap<string, NormalizedCheck>,
+  task: Readonly<{ readonly id: string }>,
+  owner: "Blocked Task" | "Task graph"
+): NormalizedCheck {
+  const check = checksByCheckId.get(task.id);
+  if (check === undefined) {
+    throw new CheckExecutionInvariantFailure(`${owner} has no normalized Check`);
+  }
+  return check;
+}
+
+function admittedExecutionFacts(
+  execution: ResolvedCheckExecutionInput
+): Omit<AdmittedCheckExecutionInput, keyof CheckExecutionState | "check" | "signal"> {
+  return {
+    clock: execution.clock ?? SYSTEM_MONOTONIC_CLOCK,
+    onAdmittedCheck: execution.onAdmittedCheck,
+    invocationId: execution.invocationId ?? DIRECT_EXECUTION_INVOCATION_ID,
+    paths: execution.paths,
+    project: execution.project
+  };
+}

package/src/project-run/check-execution/terminal-result.ts

@@ -1,4 +1,5 @@
 import type { CheckMessage } from "../../check/check.ts";
+import type { HandoffProviderIdentity } from "../../check/handoff-provider-identity.ts";
 import {
   hasRequiredAndOptionalRecordKeys,
   snapshotClosedRecord
@@ -11,10 +12,17 @@ import { parseCheckMessages } from "./messages.ts";
  * Core; this adapter never validates outcome data or reasons.
  */
 export interface ParsedCheckTerminalResult {
+  readonly handoff: ParsedCheckTerminalHandoff | undefined;
   readonly messages: readonly CheckMessage[];
   readonly result: StrippedTerminalResult;
 }
 
+/** A validated reference held only until its owning Core terminal settlement accepts it. */
+export interface ParsedCheckTerminalHandoff {
+  readonly identity: HandoffProviderIdentity;
+  readonly value: object;
+}
+
 type StrippedTerminalResult =
   | Readonly<{ readonly status: "passed" | "failed"; readonly data: unknown }>
   | Readonly<{ readonly status: "not-applicable"; readonly reason?: unknown }>
@@ -25,50 +33,121 @@ type StrippedTerminalResult =
  * closed author result. Any malformed attachment rejects the whole value so a
  * valid prefix can never escape into lifecycle or Run result state.
  */
-export function parseCheckTerminalResult(value: unknown): ParsedCheckTerminalResult | undefined {
+export function parseCheckTerminalResult(
+  value: unknown,
+  handoffIdentity: HandoffProviderIdentity | undefined
+): ParsedCheckTerminalResult | undefined {
   const terminal = snapshotClosedRecord(value);
   if (terminal === undefined || typeof terminal.status !== "string") return undefined;
 
-  const result = strippedTerminalResult(terminal);
+  const result = strippedTerminalResult(terminal, handoffIdentity);
   if (result === undefined) return undefined;
   const messages = parseCheckMessages(terminal.messages);
-  return messages === undefined ? undefined : Object.freeze({ messages, result });
+  const handoff = terminalHandoff(terminal, handoffIdentity);
+  return messages === undefined || handoff === null
+    ? undefined
+    : Object.freeze({ handoff, messages, result });
+}
+
+/**
+ * A declared provider result can contain an invocation-private reference. Diagnostics
+ * retain only its parsed terminal result, and represent malformed values as null.
+ */
+export function diagnosticCallbackResult(
+  value: unknown,
+  handoffIdentity: HandoffProviderIdentity | undefined
+): unknown {
+  const terminal = snapshotClosedRecord(value);
+  if (
+    handoffIdentity === undefined &&
+    (terminal === undefined || !Object.hasOwn(terminal, "handoff"))
+  ) {
+    return value;
+  }
+  return parseCheckTerminalResult(value, handoffIdentity)?.result ?? null;
 }
 
 function strippedTerminalResult(
-  terminal: Readonly<Record<string, unknown>>
+  terminal: Readonly<Record<string, unknown>>,
+  handoffIdentity: HandoffProviderIdentity | undefined
 ): StrippedTerminalResult | undefined {
   switch (terminal.status) {
     case "passed":
+      return strippedPassedTerminalResult(terminal, handoffIdentity);
     case "failed":
-      return hasRequiredAndOptionalRecordKeys(terminal, {
-        required: ["status", "data"],
-        optional: ["messages"]
-      })
-        ? Object.freeze({ status: terminal.status, data: terminal.data })
-        : undefined;
+      return strippedFailedTerminalResult(terminal);
     case "not-applicable":
-      if (
-        !hasRequiredAndOptionalRecordKeys(terminal, {
-          required: ["status"],
-          optional: ["reason", "messages"]
-        })
-      ) {
-        return undefined;
-      }
-      return Object.freeze(
-        Object.hasOwn(terminal, "reason")
-          ? { status: "not-applicable", reason: terminal.reason }
-          : { status: "not-applicable" }
-      );
+      return strippedNotApplicableTerminalResult(terminal);
     case "unavailable":
-      return hasRequiredAndOptionalRecordKeys(terminal, {
-        required: ["status", "reason"],
-        optional: ["messages"]
-      })
-        ? Object.freeze({ status: "unavailable", reason: terminal.reason })
-        : undefined;
+      return strippedUnavailableTerminalResult(terminal);
     default:
       return undefined;
   }
 }
+
+/** A declared provider can only publish its reference alongside a passed data result. */
+function strippedPassedTerminalResult(
+  terminal: Readonly<Record<string, unknown>>,
+  handoffIdentity: HandoffProviderIdentity | undefined
+): StrippedTerminalResult | undefined {
+  const required =
+    handoffIdentity === undefined ? ["status", "data"] : ["status", "data", "handoff"];
+  return hasRequiredAndOptionalRecordKeys(terminal, { required, optional: ["messages"] })
+    ? Object.freeze({ status: "passed", data: terminal.data })
+    : undefined;
+}
+
+/** Failed results retain canonical data but never carry an invocation-private handoff. */
+function strippedFailedTerminalResult(
+  terminal: Readonly<Record<string, unknown>>
+): StrippedTerminalResult | undefined {
+  return hasRequiredAndOptionalRecordKeys(terminal, {
+    required: ["status", "data"],
+    optional: ["messages"]
+  })
+    ? Object.freeze({ status: "failed", data: terminal.data })
+    : undefined;
+}
+
+function strippedNotApplicableTerminalResult(
+  terminal: Readonly<Record<string, unknown>>
+): StrippedTerminalResult | undefined {
+  if (
+    !hasRequiredAndOptionalRecordKeys(terminal, {
+      required: ["status"],
+      optional: ["reason", "messages"]
+    })
+  ) {
+    return undefined;
+  }
+  return Object.freeze(
+    Object.hasOwn(terminal, "reason")
+      ? { status: "not-applicable", reason: terminal.reason }
+      : { status: "not-applicable" }
+  );
+}
+
+function strippedUnavailableTerminalResult(
+  terminal: Readonly<Record<string, unknown>>
+): StrippedTerminalResult | undefined {
+  return hasRequiredAndOptionalRecordKeys(terminal, {
+    required: ["status", "reason"],
+    optional: ["messages"]
+  })
+    ? Object.freeze({ status: "unavailable", reason: terminal.reason })
+    : undefined;
+}
+
+function terminalHandoff(
+  terminal: Readonly<Record<string, unknown>>,
+  handoffIdentity: HandoffProviderIdentity | undefined
+): ParsedCheckTerminalHandoff | null | undefined {
+  if (handoffIdentity === undefined) return undefined;
+  if (terminal.status !== "passed") return undefined;
+  if (!isHandoffReference(terminal.handoff)) return null;
+  return Object.freeze({ identity: handoffIdentity, value: terminal.handoff });
+}
+
+function isHandoffReference(value: unknown): value is object {
+  return value !== null && (typeof value === "object" || typeof value === "function");
+}

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

@@ -26,7 +26,7 @@ type OutcomeCounts = {
 
 /** Settled Check facts consumed by completion and output publication. */
 export type CoreExecution = Readonly<{
-  readonly aggregate: CheckAggregate | null;
+  readonly aggregate: CheckAggregate;
   readonly checkDurations: readonly CheckDuration[];
   readonly checkMessages: readonly CheckRunMessage[];
   readonly snapshot: CoreSnapshot;
@@ -136,9 +136,23 @@ export function finalizeInvocation(
   return resolveFinalRunResult(candidate, invocation.outputs.value());
 }
 
+/** Closes invocation-owned writers after aggregation rejects without fabricating a terminal Run result. */
+export function closeAggregationFailure(invocation: Invocation): void {
+  try {
+    invocation.diagnosticLogging.close();
+  } catch {
+    // Cleanup must not replace the callback error returned to the caller.
+  }
+  try {
+    invocation.progressRendering.close();
+  } catch {
+    // Cleanup must not replace the callback error returned to the caller.
+  }
+}
+
 function terminalStatusTag(candidate: NonConfigurationRunResult): string {
-  if ("aggregate" in candidate && candidate.aggregate !== null)
-    return candidate.aggregate.toUpperCase();
+  if (candidate.kind === "output") return "OUTPUT";
+  if ("aggregate" in candidate) return candidate.aggregate.toUpperCase();
   if (candidate.kind === "cancelled") return "CANCELLED";
   return candidate.kind.toUpperCase();
 }