@zxyycom/vibe-check 0.0.1 → 0.0.3

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.ts → completion/completion.ts}

@@ -1,5 +1,5 @@
-import { resolve } from "node:path";
-import { failedOutput } from "./output-status.ts";
+import { failedOutput } from "../outputs/status.ts";
+import { resolveFinalRunResult } from "./result-resolver.ts";
 import { publishMachineOutput } from "./machine-publication.ts";
 import {
   outputFailure,
@@ -7,15 +7,15 @@ import {
   type CheckRunMessage,
   type NonConfigurationRunResult,
   type RunResultFacts
-} from "./result.ts";
-import type { CheckAggregate } from "./controls/contract.ts";
-import { diagnosticTags } from "./diagnostic-logging/logger.ts";
-import type { Invocation } from "./invocation.ts";
+} from "../result.ts";
+import type { CheckAggregate } from "../controls/contract.ts";
+import { DIAGNOSTIC_CHANNELS, diagnosticTags } from "../diagnostic-logging/logger.ts";
+import type { Invocation } from "../invocation/run.ts";
 import {
   createPublicationModelV4,
   type TrustedPublicationModelV4
-} from "../machine-output/v4/publication-model.ts";
-import type { CoreCheck, CoreSnapshot } from "../check-settlement/facts.ts";
+} from "../../machine-output/v4/publication-model.ts";
+import type { CoreCheck, CoreSnapshot } from "../../check-settlement/facts.ts";
 
 type OutcomeCounts = {
   readonly failed: number;
@@ -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;
@@ -44,10 +44,7 @@ export function completeInvocation(
       configuration: invocation.outputConfiguration.machinePublication,
       statuses: invocation.outputs,
       model,
-      directory: resolve(
-        invocation.projectRoot,
-        invocation.outputConfiguration.machinePublication.directory
-      )
+      directory: invocation.paths.machinePublicationDirectory
     });
     if (!published) return failure(invocation, facts);
   }
@@ -120,7 +117,7 @@ export function finalizeInvocation(
   candidate: NonConfigurationRunResult
 ): NonConfigurationRunResult {
   const preCloseOutputs = invocation.outputs.value();
-  invocation.diagnosticLogger.observe({
+  invocation.diagnosticLogging.core.observe({
     event: "run.terminal-before-log-close",
     tags: diagnosticTags("RUN", "TERMINAL", terminalStatusTag(candidate)),
     details: {
@@ -129,45 +126,33 @@ export function finalizeInvocation(
       outputs: preCloseOutputDetails(preCloseOutputs)
     }
   });
-  const diagnosticLoggingStatus = invocation.diagnosticLogger.close();
-  if (diagnosticLoggingStatus === "failed") invocation.outputs.failed("diagnosticLogging");
-  if (diagnosticLoggingStatus === "succeeded") invocation.outputs.succeeded("diagnosticLogging");
+  const diagnosticLoggingStatuses = invocation.diagnosticLogging.close();
+  for (const channel of DIAGNOSTIC_CHANNELS) {
+    const status = diagnosticLoggingStatuses[channel];
+    if (status === "failed") invocation.outputs.failedDiagnosticChannel(channel);
+    if (status === "succeeded") invocation.outputs.succeededDiagnosticChannel(channel);
+  }
+  invocation.progressRendering.close();
+  return resolveFinalRunResult(candidate, invocation.outputs.value());
+}
 
-  const outputs = invocation.outputs.value();
-  switch (candidate.kind) {
-    case "completed": {
-      const output = failedOutput(outputs);
-      return output === undefined
-        ? Object.freeze({ ...candidate, outputs })
-        : outputFailure(
-            candidate.declarativeFingerprint,
-            candidate.definitionWarnings,
-            outputs,
-            output,
-            finalSnapshotFacts(candidate)
-          );
-    }
-    case "output": {
-      const output = failedOutput(outputs);
-      if (output === undefined) throw new Error("Run output failed without a failed status");
-      return outputFailure(
-        candidate.declarativeFingerprint,
-        candidate.definitionWarnings,
-        outputs,
-        output,
-        finalSnapshotFacts(candidate)
-      );
-    }
-    case "planning":
-    case "cancelled":
-    case "execution":
-      return Object.freeze({ ...candidate, outputs });
+/** 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();
 }
@@ -250,14 +235,3 @@ function nonPassedFact(
     status: check.outcome.status
   });
 }
-
-function finalSnapshotFacts(
-  candidate: Extract<NonConfigurationRunResult, RunResultFacts>
-): RunResultFacts {
-  return Object.freeze({
-    aggregate: candidate.aggregate,
-    checkDurations: candidate.checkDurations,
-    checkMessages: candidate.checkMessages,
-    snapshot: candidate.snapshot
-  });
-}

package/src/project-run/{machine-publication.ts → completion/machine-publication.ts}

@@ -1,7 +1,7 @@
-import type { ProjectOutputs } from "../project-definition/project-definition.ts";
-import type { TrustedPublicationModelV4 } from "../machine-output/v4/publication-model.ts";
-import { publishScanV4 } from "../machine-output/v4/publish.ts";
-import type { OutputStatuses } from "./output-status.ts";
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+import type { TrustedPublicationModelV4 } from "../../machine-output/v4/publication-model.ts";
+import { publishScanV4 } from "../../machine-output/v4/publish.ts";
+import type { OutputStatuses } from "../outputs/status.ts";
 /** Publishes an already-trusted v4 model as the Run-owned machine output. */
 export function publishMachineOutput(
   input: Readonly<{

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

@@ -0,0 +1,60 @@
+import { failedOutput, type RunOutputStatuses } from "../outputs/status.ts";
+import { outputFailure, type NonConfigurationRunResult, type RunResultFacts } from "../result.ts";
+
+/** Resolves a terminal candidate against the output statuses after all owners have closed. */
+export function resolveFinalRunResult(
+  candidate: NonConfigurationRunResult,
+  outputs: RunOutputStatuses
+): NonConfigurationRunResult {
+  switch (candidate.kind) {
+    case "completed":
+      return resolveCompletedCandidate(candidate, outputs);
+    case "output":
+      return resolveExistingOutputCandidate(candidate, outputs);
+    case "planning":
+    case "cancelled":
+    case "execution":
+      return Object.freeze({ ...candidate, outputs });
+  }
+}
+
+function resolveCompletedCandidate(
+  candidate: Extract<NonConfigurationRunResult, { readonly kind: "completed" }>,
+  outputs: RunOutputStatuses
+): NonConfigurationRunResult {
+  const output = failedOutput(outputs);
+  if (output === undefined) return Object.freeze({ ...candidate, outputs });
+  return outputFailure(
+    candidate.declarativeFingerprint,
+    candidate.definitionWarnings,
+    outputs,
+    output,
+    finalSnapshotFacts(candidate)
+  );
+}
+
+function resolveExistingOutputCandidate(
+  candidate: Extract<NonConfigurationRunResult, { readonly kind: "output" }>,
+  outputs: RunOutputStatuses
+): NonConfigurationRunResult {
+  const output = failedOutput(outputs);
+  if (output === undefined) throw new Error("Run output failed without a failed status");
+  return outputFailure(
+    candidate.declarativeFingerprint,
+    candidate.definitionWarnings,
+    outputs,
+    output,
+    finalSnapshotFacts(candidate)
+  );
+}
+
+function finalSnapshotFacts(
+  candidate: Extract<NonConfigurationRunResult, RunResultFacts>
+): RunResultFacts {
+  return Object.freeze({
+    aggregate: candidate.aggregate,
+    checkDurations: candidate.checkDurations,
+    checkMessages: candidate.checkMessages,
+    snapshot: candidate.snapshot
+  });
+}

package/src/project-run/controls/contract.ts

@@ -1,6 +1,20 @@
 import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
-/** 单次 run 调用的闭合上下文与 output override；Project Definition 保持为 authored input。 */
+import type { CoreCheck } from "../../check-settlement/facts.ts";
+/**
+ * `run(definition, controls?)` 的第二个参数，只指定这一次怎么运行。
+ *
+ * root、flags、signal、Check 产物与日志目标以及 aggregation 属于本次调用；`outputs` 只逐字段
+ * 覆盖 Definition 的输出默认值，不修改原 Definition。Checks、Check options 与 scheduler 仍在
+ * `defineConfig(...)` 中声明，不能从这里替换；这些 Controls 不进入 Definition fingerprint。
+ */
 export interface RunControls {
+  /** 单次 diagnostic 文件命名；默认 `unique`，独占目录可选 `channel` 使用固定 Core/Scheduler 名，同名目标失败且不覆盖。 */
+  readonly diagnosticLogFileNaming?: DiagnosticLogFileNaming;
+  /** caller 为当前 Run 选择的 progress log exact target；省略时只写 terminal。 */
+  readonly progressLogFile?: string;
+  /** caller 选择的 Check-owned invocation artifact base；省略时不授予 artifact capability。 */
+  readonly checkArtifactBaseDirectory?: string;
+  /** 为本次 Run 解释有效 Check facts；省略时使用严格的 all-passed 默认折叠。 */
   readonly checkAggregation?: CheckAggregation;
   /** 仅为本次调用覆盖 Run-owned outputs。 */
   readonly outputs?: Partial<{
@@ -8,17 +22,16 @@ export interface RunControls {
     progressRendering: Partial<ProjectOutputs["progressRendering"]>;
     diagnosticLogging: Partial<ProjectOutputs["diagnosticLogging"]>;
   }>;
+  /** 本次 Run 的 flag tokens；Product 去重排序后用于 Check selection 与 callback project context。 */
   readonly flags?: readonly string[];
+  /** 项目相对输入与 output target 的解析根；省略时使用调用进程的当前工作目录。 */
   readonly projectRoot?: string;
+  /** 供 planning、preparation 与 execution 协作响应的 caller cancellation signal。 */
   readonly signal?: AbortSignal;
 }
-/** 将选定 Check statuses 折叠为 invocation aggregate 的规则。 */
-export interface CheckAggregation {
-  readonly checks: "all" | readonly string[];
-  readonly mode: "all" | "any";
-  readonly unavailable: "propagate" | "fail" | "exclude";
-  readonly notApplicable: "exclude" | "pass" | "fail";
-  readonly empty: "passed" | "failed" | "not-applicable";
-}
+/** Diagnostic 文件名选择；不改变目录、日志内容或 invocation identity。 */
+export type DiagnosticLogFileNaming = "unique" | "channel";
 /** `CheckAggregation` 计算出的 invocation 级结果。 */
 export type CheckAggregate = "passed" | "failed" | "not-applicable" | "unavailable";
+/** 同步解释本次有效 Check facts 的 caller-local aggregation。 */
+export type CheckAggregation = (checks: readonly CoreCheck[]) => CheckAggregate;

package/src/project-run/controls/outputs-override-validation.ts

@@ -1,7 +1,9 @@
 import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
-import { isContainedRelativeDirectory } from "../../project-definition/output-validation.ts";
-import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+import { isOutputDirectory } from "../../project-definition/output-validation.ts";
+import { parseProgressRenderingFields } from "../../project-definition/progress-rendering-output.ts";
+import type { ProgressRenderingOutput } from "../../project-definition/progress-rendering-output.ts";
 import type { RunControls } from "./contract.ts";
+import type { RunControlDiagnostic, RunControlValidationResult } from "./validation-result.ts";
 
 type DirectoryOutputOverride = Readonly<{
   readonly directory?: string;
@@ -9,78 +11,99 @@ type DirectoryOutputOverride = Readonly<{
 }>;
 
 /** Parses invocation-local outputs without changing Definition defaults. */
-export function parseOutputsOverride(value: unknown): RunControls["outputs"] | undefined {
+export function parseOutputsOverride(
+  value: unknown
+): RunControlValidationResult<RunControls["outputs"]> {
+  if (value === undefined) return { ok: true, value: undefined };
   const data = snapshotClosedRecord(value);
-  if (
-    data === undefined ||
-    Object.keys(data).some(
-      (key) =>
-        key !== "machinePublication" && key !== "progressRendering" && key !== "diagnosticLogging"
-    )
-  )
-    return undefined;
+  const path = "controls.outputs";
+  if (data === undefined) return invalidOutput(path, "invalid-value", "plain-data-object");
+  const unknownKey = Object.keys(data).find(
+    (key) =>
+      key !== "machinePublication" && key !== "progressRendering" && key !== "diagnosticLogging"
+  );
+  if (unknownKey !== undefined) return invalidOutput(`${path}.${unknownKey}`, "unknown-key");
   const machinePublication = optionalOutput(
     data,
     "machinePublication",
     parseDirectoryOutputOverride
   );
-  const progressRendering = optionalOutput(data, "progressRendering", parseProgressOutputOverride);
-  const diagnosticLogging = optionalOutput(
-    data,
-    "diagnosticLogging",
-    parseDiagnosticLoggingOverride
-  );
-  if (!machinePublication.ok || !progressRendering.ok || !diagnosticLogging.ok) return undefined;
-  return Object.freeze({
-    ...(machinePublication.value === undefined
-      ? {}
-      : { machinePublication: machinePublication.value }),
-    ...(progressRendering.value === undefined
-      ? {}
-      : { progressRendering: progressRendering.value }),
-    ...(diagnosticLogging.value === undefined ? {} : { diagnosticLogging: diagnosticLogging.value })
-  });
+  if (!machinePublication.ok) return machinePublication;
+  const progressRendering = optionalOutput(data, "progressRendering", parseProgressOverride);
+  if (!progressRendering.ok) return progressRendering;
+  const diagnosticLogging = optionalOutput(data, "diagnosticLogging", parseDirectoryOutputOverride);
+  if (!diagnosticLogging.ok) return diagnosticLogging;
+  return {
+    ok: true,
+    value: Object.freeze({
+      ...(machinePublication.value === undefined
+        ? {}
+        : { machinePublication: machinePublication.value }),
+      ...(progressRendering.value === undefined
+        ? {}
+        : { progressRendering: progressRendering.value }),
+      ...(diagnosticLogging.value === undefined
+        ? {}
+        : { diagnosticLogging: diagnosticLogging.value })
+    })
+  };
 }
 function optionalOutput<T>(
   value: Readonly<Record<string, unknown>>,
   key: string,
-  parse: (candidate: unknown) => T | undefined
-): Readonly<{ readonly ok: boolean; readonly value?: T }> {
-  if (value[key] === undefined) return Object.freeze({ ok: true });
-  const parsed = parse(value[key]);
-  return parsed === undefined
-    ? Object.freeze({ ok: false })
-    : Object.freeze({ ok: true, value: parsed });
+  parse: (candidate: unknown, path: string) => RunControlValidationResult<T>
+): RunControlValidationResult<T | undefined> {
+  if (value[key] === undefined) return { ok: true, value: undefined };
+  return parse(value[key], `controls.outputs.${key}`);
+}
+function parseProgressOverride(
+  value: unknown,
+  path: string
+): RunControlValidationResult<Partial<ProgressRenderingOutput>> {
+  const fields = parseProgressRenderingFields(value);
+  if (fields.ok) return fields;
+  return invalidOutput(
+    fields.key === null ? path : `${path}.${fields.key}`,
+    fields.reason,
+    fields.expected
+  );
 }
-function parseDirectoryOutputOverride(value: unknown): DirectoryOutputOverride | undefined {
+function parseDirectoryOutputOverride(
+  value: unknown,
+  path: string
+): RunControlValidationResult<DirectoryOutputOverride> {
   const data = snapshotClosedRecord(value);
+  if (data === undefined) return invalidOutput(path, "invalid-value", "plain-data-object");
+  const unknownKey = Object.keys(data).find((key) => key !== "directory" && key !== "enabled");
+  if (unknownKey !== undefined) return invalidOutput(`${path}.${unknownKey}`, "unknown-key");
   if (
-    data === undefined ||
-    Object.keys(data).some((key) => key !== "directory" && key !== "enabled")
+    data.directory !== undefined &&
+    (typeof data.directory !== "string" || !isOutputDirectory(data.directory))
   )
-    return undefined;
-  if (data.directory !== undefined && typeof data.directory !== "string") return undefined;
-  if (data.enabled !== undefined && typeof data.enabled !== "boolean") return undefined;
-  return Object.freeze({
-    ...(data.directory === undefined ? {} : { directory: data.directory }),
-    ...(data.enabled === undefined ? {} : { enabled: data.enabled })
-  });
-}
-function parseProgressOutputOverride(
-  value: unknown
-): Partial<ProjectOutputs["progressRendering"]> | undefined {
-  const data = snapshotClosedRecord(value);
-  if (data === undefined || Object.keys(data).some((key) => key !== "enabled")) return undefined;
-  if (data.enabled !== undefined && typeof data.enabled !== "boolean") return undefined;
-  return Object.freeze(data.enabled === undefined ? {} : { enabled: data.enabled });
+    return invalidOutput(`${path}.directory`, "invalid-value", "non-empty-string-without-nul");
+  if (data.enabled !== undefined && typeof data.enabled !== "boolean") {
+    return invalidOutput(`${path}.enabled`, "invalid-value", "boolean");
+  }
+  return {
+    ok: true,
+    value: Object.freeze({
+      ...(data.directory === undefined ? {} : { directory: data.directory }),
+      ...(data.enabled === undefined ? {} : { enabled: data.enabled })
+    })
+  };
 }
 
-function parseDiagnosticLoggingOverride(
-  value: unknown
-): Partial<ProjectOutputs["diagnosticLogging"]> | undefined {
-  const parsed = parseDirectoryOutputOverride(value);
-  return parsed === undefined ||
-    (parsed.directory !== undefined && !isContainedRelativeDirectory(parsed.directory))
-    ? undefined
-    : parsed;
+function invalidOutput(
+  path: string,
+  reason: RunControlDiagnostic["reason"],
+  expected?: RunControlDiagnostic["expected"]
+): RunControlValidationResult<never> {
+  return Object.freeze({
+    ok: false,
+    error: Object.freeze({
+      kind: "invalid-run-controls",
+      path,
+      ...(reason === "invalid-value" && expected !== undefined ? { reason, expected } : { reason })
+    })
+  });
 }

package/src/project-run/controls/validation-result.ts

@@ -1,9 +1,20 @@
-/** Diagnostic emitted when one invocation control is not a closed supported value. */
-export interface RunControlDiagnostic {
-  readonly kind: "invalid-run-controls";
-  readonly path: string;
-  readonly reason: "invalid-value" | "unknown-key";
-}
+import type { ProgressRenderingFieldExpectation } from "../../project-definition/progress-rendering-output.ts";
+
+/** 本次 controls 不符合封闭输入契约时的定位诊断；不包含被拒绝的原始值。 */
+export type RunControlDiagnostic = Readonly<
+  {
+    readonly kind: "invalid-run-controls";
+    /** 被拒绝的字段；对象本身无法安全读取时指向该对象。 */
+    readonly path: string;
+  } & (
+    | {
+        readonly reason: "invalid-value";
+        /** 输出覆盖值非法时的合法值要求；未提供此提示的诊断省略。 */
+        readonly expected?: ProgressRenderingFieldExpectation | "non-empty-string-without-nul";
+      }
+    | { readonly reason: "unknown-key"; readonly expected?: never }
+  )
+>;
 
 /** Closed validation result for a Run-owned invocation control. */
 export type RunControlValidationResult<T> = Readonly<