@zxyycom/vibe-check 0.0.1 → 0.0.2

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;
@@ -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,40 +126,14 @@ 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 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 });
+  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());
 }
 
 function terminalStatusTag(candidate: NonConfigurationRunResult): string {
@@ -250,14 +221,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,19 @@
 import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
-/** 单次 run 调用的闭合上下文与 output override；Project Definition 保持为 authored input。 */
+/**
+ * `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 statuses；省略时结果的 `aggregate` 为 `null`。 */
   readonly checkAggregation?: CheckAggregation;
   /** 仅为本次调用覆盖 Run-owned outputs。 */
   readonly outputs?: Partial<{
@@ -8,16 +21,26 @@ 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、preflight 与 execution 协作响应的 caller cancellation signal。 */
   readonly signal?: AbortSignal;
 }
+/** Diagnostic 文件名选择；不改变目录、日志内容或 invocation identity。 */
+export type DiagnosticLogFileNaming = "unique" | "channel";
 /** 将选定 Check statuses 折叠为 invocation aggregate 的规则。 */
 export interface CheckAggregation {
-  readonly checks: "all" | readonly string[];
+  /** `all` 选择全部 Check，ID 数组选择明确集合，`effective` 复用本 invocation 的 flag-and-dependency selection。 */
+  readonly checks: "all" | "effective" | readonly string[];
+  /** `all` 要求所有纳入状态通过；`any` 只要求至少一个纳入状态通过。 */
   readonly mode: "all" | "any";
+  /** 将 `unavailable` 原样传播、按失败纳入，或从 `all`/`any` 计算中排除。 */
   readonly unavailable: "propagate" | "fail" | "exclude";
+  /** 将 `not-applicable` 从计算中排除，或按通过/失败纳入。 */
   readonly notApplicable: "exclude" | "pass" | "fail";
+  /** 选择为空或所有状态都被排除时返回的明确 aggregate。 */
   readonly empty: "passed" | "failed" | "not-applicable";
 }
 /** `CheckAggregation` 计算出的 invocation 级结果。 */

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<

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

@@ -1,15 +1,39 @@
 import { snapshotClosedArray } from "../../data-boundary/closed-values.ts";
+import { isOutputDirectory } from "../../project-definition/output-validation.ts";
 import { isNonArrayRecord, isUnknownArray } from "../../data-boundary/value-shapes.ts";
 import { parseOutputsOverride } from "./outputs-override-validation.ts";
 import type { RunControlDiagnostic, RunControlValidationResult } from "./validation-result.ts";
-import type { CheckAggregation, RunControls } from "./contract.ts";
+import type { CheckAggregation, DiagnosticLogFileNaming, RunControls } from "./contract.ts";
 
-const RUN_CONTROL_KEYS = ["checkAggregation", "outputs", "flags", "projectRoot", "signal"] as const;
+const RUN_CONTROL_KEYS = [
+  "checkArtifactBaseDirectory",
+  "checkAggregation",
+  "diagnosticLogFileNaming",
+  "progressLogFile",
+  "outputs",
+  "flags",
+  "projectRoot",
+  "signal"
+] as const;
 const CHECK_AGGREGATION_MODES = ["all", "any"] as const;
 const UNAVAILABLE_HANDLING = ["propagate", "fail", "exclude"] as const;
 const NOT_APPLICABLE_HANDLING = ["exclude", "pass", "fail"] as const;
 const EMPTY_AGGREGATION_RESULTS = ["passed", "failed", "not-applicable"] as const;
 
+interface ParsedInvocationOutputTargets {
+  readonly diagnosticLogFileNaming: DiagnosticLogFileNaming | undefined;
+  readonly checkArtifactBaseDirectory: string | undefined;
+  readonly progressLogFile: string | undefined;
+}
+
+interface ParsedRunControlFields extends ParsedInvocationOutputTargets {
+  readonly checkAggregation: CheckAggregation | undefined;
+  readonly flags: readonly string[];
+  readonly outputs: RunControls["outputs"] | undefined;
+  readonly projectRoot: string | undefined;
+  readonly signal: AbortSignal | undefined;
+}
+
 export function validateRunControls(value: unknown = {}): RunControlValidationResult<RunControls> {
   try {
     return validateRunControlsValue(value);
@@ -21,28 +45,88 @@ export function validateRunControls(value: unknown = {}): RunControlValidationRe
 function validateRunControlsValue(value: unknown): RunControlValidationResult<RunControls> {
   const data = exactControlRecord(value);
   if (!data.ok) return data;
-  const flags = parseFlags(data.value.flags);
+  const fields = parseRunControlFields(data.value);
+  if (!fields.ok) return fields;
+  return Object.freeze({ ok: true, value: runControlsFromFields(fields.value) });
+}
+
+function parseRunControlFields(
+  data: Readonly<Record<string, unknown>>
+): RunControlValidationResult<ParsedRunControlFields> {
+  const outputTargets = parseInvocationOutputTargets(data);
+  if (!outputTargets.ok) return outputTargets;
+  const flags = parseFlags(data.flags);
   if (!flags.ok) return flags;
-  const checkAggregation = parseOptionalCheckAggregation(data.value.checkAggregation);
+  const checkAggregation = parseOptionalCheckAggregation(data.checkAggregation);
   if (!checkAggregation.ok) return checkAggregation;
-  const outputs = optionalControl(data.value.outputs, parseOutputsOverride, "controls.outputs");
+  const outputs = parseOutputsOverride(data.outputs);
   if (!outputs.ok) return outputs;
-  const projectRoot = optionalControl(data.value.projectRoot, parseString, "controls.projectRoot");
+  const projectRoot = optionalControl(data.projectRoot, parseString, "controls.projectRoot");
   if (!projectRoot.ok) return projectRoot;
-  const signal = optionalControl(data.value.signal, parseAbortSignal, "controls.signal");
+  const signal = optionalControl(data.signal, parseAbortSignal, "controls.signal");
   if (!signal.ok) return signal;
   return Object.freeze({
     ok: true,
     value: Object.freeze({
-      ...(checkAggregation.value === undefined ? {} : { checkAggregation: checkAggregation.value }),
-      ...(outputs.value === undefined ? {} : { outputs: outputs.value }),
+      ...outputTargets.value,
+      checkAggregation: checkAggregation.value,
       flags: flags.value,
-      ...(projectRoot.value === undefined ? {} : { projectRoot: projectRoot.value }),
-      ...(signal.value === undefined ? {} : { signal: signal.value })
+      outputs: outputs.value,
+      projectRoot: projectRoot.value,
+      signal: signal.value
+    })
+  });
+}
+
+/** Parse caller-owned invocation output targets separately from Run execution controls. */
+function parseInvocationOutputTargets(
+  data: Readonly<Record<string, unknown>>
+): RunControlValidationResult<ParsedInvocationOutputTargets> {
+  const diagnosticLogFileNaming = optionalControl(
+    data.diagnosticLogFileNaming,
+    parseDiagnosticLogFileNaming,
+    "controls.diagnosticLogFileNaming"
+  );
+  if (!diagnosticLogFileNaming.ok) return diagnosticLogFileNaming;
+  const checkArtifactBaseDirectory = optionalControl(
+    data.checkArtifactBaseDirectory,
+    parseOutputDirectory,
+    "controls.checkArtifactBaseDirectory"
+  );
+  if (!checkArtifactBaseDirectory.ok) return checkArtifactBaseDirectory;
+  const progressLogFile = optionalControl(
+    data.progressLogFile,
+    parseOutputDirectory,
+    "controls.progressLogFile"
+  );
+  if (!progressLogFile.ok) return progressLogFile;
+  return Object.freeze({
+    ok: true,
+    value: Object.freeze({
+      diagnosticLogFileNaming: diagnosticLogFileNaming.value,
+      checkArtifactBaseDirectory: checkArtifactBaseDirectory.value,
+      progressLogFile: progressLogFile.value
     })
   });
 }
 
+function runControlsFromFields(fields: ParsedRunControlFields): RunControls {
+  return Object.freeze({
+    ...(fields.diagnosticLogFileNaming === undefined
+      ? {}
+      : { diagnosticLogFileNaming: fields.diagnosticLogFileNaming }),
+    ...(fields.checkArtifactBaseDirectory === undefined
+      ? {}
+      : { checkArtifactBaseDirectory: fields.checkArtifactBaseDirectory }),
+    ...(fields.checkAggregation === undefined ? {} : { checkAggregation: fields.checkAggregation }),
+    ...(fields.outputs === undefined ? {} : { outputs: fields.outputs }),
+    ...(fields.progressLogFile === undefined ? {} : { progressLogFile: fields.progressLogFile }),
+    flags: fields.flags,
+    ...(fields.projectRoot === undefined ? {} : { projectRoot: fields.projectRoot }),
+    ...(fields.signal === undefined ? {} : { signal: fields.signal })
+  });
+}
+
 function exactControlRecord(
   value: unknown
 ): RunControlValidationResult<Readonly<Record<string, unknown>>> {
@@ -53,6 +137,10 @@ function exactControlRecord(
     : invalidRunControl(`controls.${unknownKey}`, "unknown-key");
 }
 
+function parseDiagnosticLogFileNaming(value: unknown): DiagnosticLogFileNaming | undefined {
+  return value === "unique" || value === "channel" ? value : undefined;
+}
+
 function optionalControl<T>(
   value: unknown,
   parse: (candidate: unknown) => T | undefined,
@@ -88,7 +176,10 @@ function parseOptionalCheckAggregation(
   if (value === undefined) return Object.freeze({ ok: true, value: undefined });
   const data = exactKeys(value, ["checks", "mode", "unavailable", "notApplicable", "empty"]);
   if (data === undefined) return invalidControls("controls.checkAggregation");
-  const checks = data.checks === "all" ? "all" : parseClosedCheckIds(data.checks);
+  const checks =
+    data.checks === "all" || data.checks === "effective"
+      ? data.checks
+      : parseClosedCheckIds(data.checks);
   if (checks === undefined) return invalidControls("controls.checkAggregation.checks");
   const mode = parseLiteral(data.mode, CHECK_AGGREGATION_MODES);
   const unavailable = parseLiteral(data.unavailable, UNAVAILABLE_HANDLING);
@@ -161,6 +252,10 @@ function parseString(value: unknown): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
 
+function parseOutputDirectory(value: unknown): string | undefined {
+  return typeof value === "string" && isOutputDirectory(value) ? value : undefined;
+}
+
 function invalidControls(path: string): RunControlValidationResult<never> {
   return invalidRunControl(path, "invalid-value");
 }