@zxyycom/vibe-check 0.0.1 → 0.0.3

package/types/project-run/check-execution/execution-finalization.d.ts

@@ -1,18 +1,28 @@
-import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
-import { CheckExecutionInvariantFailure, type CheckIdentity } from "./execution-settlement.ts";
-import type { PreparedCheck } from "./preflight.ts";
-import type { CheckExecutionState, ResolvedCheckExecution } from "./resolved-checks.ts";
+import type { NormalizedCheck, SchedulerMeasurementContext } from "../../project-definition/project-definition.ts";
+import { CheckExecutionInvariantFailure, type CheckIdentity, type CheckExecutionState } from "./execution-settlement.ts";
+import type { ResolvedCheckExecution } from "./resolved-execution-result.ts";
 /** Closes the task graph, lifecycle facts, and canonical Check summaries as one Run boundary. */
 export declare function closeResolvedChecks(input: Readonly<{
     readonly allChecks: readonly NormalizedCheck[];
-    readonly graphRun: Awaited<ReturnType<typeof import("../task-scheduler/scheduler.ts").runTaskGraph<void>>>;
-    readonly readyChecks: readonly PreparedCheck[];
+    readonly effectiveCheckIds: readonly string[];
+    readonly graphRun: Awaited<ReturnType<typeof import("../task-scheduler/scheduler.ts").runTaskGraph<boolean>>>;
     readonly state: CheckExecutionState;
 }>): ResolvedCheckExecution;
+export declare function closeAdmissionPolicyFailed(input: Readonly<{
+    readonly normalizedChecks: readonly NormalizedCheck[];
+    readonly state: CheckExecutionState;
+    readonly terminalSchedulerMeasurement?: SchedulerMeasurementContext;
+}>): ResolvedCheckExecution;
 export declare function closeCancelledExecution(input: Readonly<{
     readonly normalizedChecks: readonly NormalizedCheck[];
-    readonly preparedChecks: readonly PreparedCheck[];
     readonly state: CheckExecutionState;
+    readonly terminalSchedulerMeasurement?: SchedulerMeasurementContext;
 }>): ResolvedCheckExecution;
-export declare function checkIdentity(check: Pick<NormalizedCheck, "definition" | "visibility">): CheckIdentity;
+export declare function checkIdentity(check: Pick<NormalizedCheck, "definition" | "omitQuietPassedRow">): CheckIdentity;
 export declare function trustedFailure(error: unknown): CheckExecutionInvariantFailure;
+/** Closes one Scheduler-blocked Check before a terminal observer may start. */
+export declare function settleBlockedDependent(input: Readonly<{
+    readonly check: NormalizedCheck;
+    readonly dependencyIds: readonly string[];
+    readonly state: CheckExecutionState;
+}>): void;

package/types/project-run/check-execution/execution-settlement.d.ts

@@ -1,12 +1,14 @@
-import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.ts";
+import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { HandoffProviderIdentity } from "../../check/handoff-provider-identity.ts";
 import type { CoreCheckSession } from "../../check-settlement/session.ts";
 import { type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
-import type { CheckExecutionLifecycle } from "./resolved-checks.ts";
+import { type ParsedCheckTerminalHandoff } from "./terminal-result.ts";
+import type { CheckExecutionLifecycle } from "./lifecycle.ts";
 import type { executeCheckCallback } from "./callback.ts";
 export type CheckIdentity = Readonly<{
     readonly checkId: string;
     readonly displayName: string;
-    readonly visibility: CheckVisibility;
+    readonly omitQuietPassedRow: boolean;
 }>;
 export interface SettledCheckFacts {
     readonly durationMs: number | null;
@@ -14,28 +16,37 @@ export interface SettledCheckFacts {
 }
 export type CheckExecutionSettlementState = Readonly<{
     readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly handoffsByCheckId: Map<string, ParsedCheckTerminalHandoff>;
     readonly lifecycle: CheckExecutionLifecycle | undefined;
+    readonly session: CoreCheckSession;
     readonly settledFactsByCheckId: Map<string, SettledCheckFacts>;
 }>;
+/** Mutable execution session state shared by execution and terminal finalization. */
+export type CheckExecutionState = CheckExecutionSettlementState;
 export declare class CheckExecutionInvariantFailure extends Error {
     constructor(message: string);
 }
-export declare function settleCallback(input: Readonly<{
+type SettleCallbackInput = Readonly<{
     readonly callback: Awaited<ReturnType<typeof executeCheckCallback>>;
     readonly checkId: string;
     readonly diagnosticLogger: DiagnosticLogger | undefined;
-    readonly preflightMessages: readonly CheckMessage[];
+    readonly handoff: HandoffProviderIdentity | undefined;
+    readonly preparationMessages: readonly CheckMessage[];
     readonly scope: ReturnType<CoreCheckSession["openCheckScope"]>;
-}>): Readonly<{
+    readonly state: CheckExecutionSettlementState;
+}>;
+type SettledCallback = Readonly<{
     readonly messages: readonly CheckMessage[];
     readonly outcome: CheckOutcome;
 }>;
+export declare function settleCallback(input: SettleCallbackInput): SettledCallback;
 /** Records one terminal Check lifecycle fact after its owning Core scope has closed. */
 export declare function recordSettledCheck(input: Readonly<{
     readonly check: CheckIdentity;
     readonly durationMs: number | null;
     readonly messages: readonly CheckMessage[];
     readonly outcome: CheckOutcome;
-    readonly phase: "execution" | "preflight";
+    readonly phase: "control" | "dependency" | "execution" | "preparation";
     readonly state: CheckExecutionSettlementState;
 }>): void;
+export {};

package/types/project-run/check-execution/flag-controls.d.ts

@@ -0,0 +1,27 @@
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+export declare const FLAG_CONDITION_NOT_MATCHED_CODE = "flag-condition-not-matched";
+type FlagControlledCheck = Pick<NormalizedCheck, "definition" | "omitQuietPassedRow">;
+type FlagControlOutcome = Readonly<{
+    readonly status: "not-applicable";
+    readonly reason: Readonly<{
+        readonly code: typeof FLAG_CONDITION_NOT_MATCHED_CODE;
+    }>;
+}>;
+export type FlagControlSettlement = Readonly<{
+    readonly check: FlagControlledCheck;
+    readonly outcome: FlagControlOutcome;
+}>;
+/**
+ * Selects canonical Check IDs for direct flag matches and their opt-in
+ * `dependsOn` closures after complete static graph validation.
+ */
+export declare function selectEffectiveCheckIds(checks: readonly NormalizedCheck[], flags: readonly string[]): readonly string[];
+/** Resolves all flag-controlled outcomes before Scheduler admission or Check-owned work. */
+export declare function resolveFlagControlSettlements(input: Readonly<{
+    readonly checks: readonly NormalizedCheck[];
+    readonly diagnosticLogger?: DiagnosticLogger;
+    readonly effectiveCheckIds: readonly string[];
+    readonly signal: AbortSignal | undefined;
+}>): readonly FlagControlSettlement[];
+export {};

package/types/project-run/check-execution/lifecycle.d.ts

@@ -0,0 +1,24 @@
+import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { CoreRecord } from "../../check-settlement/facts.ts";
+/** Private invocation-wide barrier that is independent from per-Check lifecycle facts. */
+export type InvocationLifecycle = Readonly<{
+    /** Fires once after Product accepts every flag-control settlement and before Scheduler work. */
+    readonly selectionSettled: () => void;
+}>;
+/** Private per-Check lifecycle presentation and accounting channel. */
+export type CheckExecutionLifecycle = Readonly<{
+    readonly started: (fact: CheckStartedFact) => void;
+    readonly settled: (fact: CheckSettledFact) => void;
+}>;
+export type CheckStartedFact = Readonly<{
+    checkId: string;
+    displayName: string;
+    omitQuietPassedRow: boolean;
+}>;
+export type CheckSettledFact = CheckStartedFact & Readonly<{
+    durationMs: number | null;
+    messages: readonly CheckMessage[];
+    records: readonly CoreRecord[];
+    outcome: CheckOutcome;
+    omitQuietPassedRow: boolean;
+}>;

package/types/project-run/check-execution/messages.d.ts

@@ -1,3 +1,5 @@
 import type { CheckMessage } from "../../check/check.ts";
+/** Preserves phase-local order while avoiding mutable or per-call empty message collections. */
+export declare function combineCheckMessages(...collections: readonly (readonly CheckMessage[])[]): readonly CheckMessage[];
 /** Parses the shared closed Check-message attachment without retaining author input. */
 export declare function parseCheckMessages(value: unknown): readonly CheckMessage[] | undefined;

package/types/project-run/check-execution/plan.d.ts

@@ -1,10 +1,9 @@
 import type { TaskGraph } from "../task-scheduler/graph.ts";
 import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { type ResourceUnitMapping } from "../../project-definition/resource-unit-mapping.ts";
 /**
  * Pure executable-Check projection. Check ids are the only scheduler Task
  * identities: containment has already been resolved by Definition and has no
  * runtime alias or completion semantics here.
  */
-export declare function planStaticCheckGraph(checks: readonly NormalizedCheck[], options?: Readonly<{
-    readonly alreadySettledCheckIds?: ReadonlySet<string>;
-}>): TaskGraph;
+export declare function planStaticCheckGraph(checks: readonly NormalizedCheck[], resourceCapacities?: ResourceUnitMapping): TaskGraph;

package/types/project-run/check-execution/{preflight-result.d.ts → preparation-result.d.ts}

@@ -1,5 +1,5 @@
 import type { CheckMessage } from "../../check/check.ts";
-export type ParsedCheckPreflightResult = Readonly<{
+export type ParsedCheckPreparationResult = Readonly<{
     readonly status: "success";
     readonly preparedOptions: unknown;
     readonly messages: readonly CheckMessage[];
@@ -19,5 +19,5 @@ export type ParsedCheckPreflightResult = Readonly<{
     };
     readonly messages: readonly CheckMessage[];
 }>;
-/** Parses the closed result vocabulary returned by one trusted Check preflight. */
-export declare function parseCheckPreflightResult(value: unknown): ParsedCheckPreflightResult | undefined;
+/** Parses the closed result vocabulary returned by one trusted Check preparation. */
+export declare function parseCheckPreparationResult(value: unknown): ParsedCheckPreparationResult | undefined;

package/types/project-run/check-execution/preparation.d.ts

@@ -0,0 +1,29 @@
+import type { CheckMessage, CheckOutcome, CheckProjectContext } from "../../check/check.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+export type PreparedCheck = Omit<NormalizedCheck, "options" | "prepare"> & Readonly<{
+    readonly options: object;
+    readonly preparationMessages: readonly CheckMessage[];
+}>;
+type BlockedCheck = Pick<NormalizedCheck, "definition" | "omitQuietPassedRow"> & Readonly<{
+    readonly preparationMessages: readonly CheckMessage[];
+}>;
+export type ReadyCheckPreparationResolution = Readonly<{
+    readonly kind: "ready";
+    readonly check: PreparedCheck;
+}>;
+export type BlockedCheckPreparationResolution = Readonly<{
+    readonly kind: "blocked";
+    readonly check: BlockedCheck;
+    readonly outcome: CheckOutcome;
+}>;
+export type CheckPreparationResolution = ReadyCheckPreparationResolution | BlockedCheckPreparationResolution;
+type PrepareCheckInput = Readonly<{
+    readonly check: NormalizedCheck;
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly project: CheckProjectContext;
+    readonly signal: AbortSignal | undefined;
+}>;
+/** Resolves one Check's task-local preparation after Scheduler admission. */
+export declare function prepareCheck(input: PrepareCheckInput): Promise<CheckPreparationResolution>;
+export {};

package/types/project-run/check-execution/ready-check-execution.d.ts

@@ -0,0 +1,18 @@
+/** Executes and settles a Check after its task-local preparation has admitted it. */
+import type { CheckProjectContext } from "../../check/check.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { type ResolvedInvocationPaths } from "../invocation/paths.ts";
+import { type CheckExecutionState } from "./execution-settlement.ts";
+import type { ReadyCheckPreparationResolution } from "./preparation.ts";
+export type ReadyCheckExecutionInput = CheckExecutionState & Readonly<{
+    readonly check: NormalizedCheck;
+    readonly clock: Readonly<{
+        now(): number;
+    }>;
+    readonly invocationId: string;
+    readonly paths: ResolvedInvocationPaths | undefined;
+    readonly prepare: ReadyCheckPreparationResolution;
+    readonly project: CheckProjectContext;
+    readonly signal: AbortSignal;
+}>;
+export declare function executeReadyCheck(input: ReadyCheckExecutionInput): Promise<boolean>;

package/types/project-run/check-execution/resolved-checks.d.ts

@@ -1,51 +1,44 @@
-import type { CheckMessage, CheckOutcome, CheckProjectContext, CheckVisibility } from "../../check/check.ts";
-import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
-import { type CoreCheckSession } from "../../check-settlement/session.ts";
-import { type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
-import { type CheckExecutionSettlementState } from "./execution-settlement.ts";
-/** Private Run handoff for Check lifecycle presentation and accounting. */
-export type CheckExecutionLifecycle = Readonly<{
-    readonly started: (fact: CheckStartedFact) => void;
-    readonly settled: (fact: CheckSettledFact) => void;
-}>;
+import type { CheckProjectContext } from "../../check/check.ts";
+import type { NormalizedCheck, SchedulerTerminalEffect } from "../../project-definition/project-definition.ts";
+import type { ResourceUnitMapping } from "../../project-definition/resource-unit-mapping.ts";
+import type { DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+import type { AdmissionSelectionPolicy } from "../task-scheduler/admission-selection-policy.ts";
+import type { SchedulerPerformanceDiagnosticsInput } from "../task-scheduler/measurement/diagnostics.ts";
+import type { ResolvedInvocationPaths } from "../invocation/paths.ts";
+import type { CheckExecutionLifecycle, InvocationLifecycle } from "./lifecycle.ts";
+import type { CheckExecutionClock } from "./admitted-check-execution.ts";
+import type { ResolvedCheckExecution } from "./resolved-execution-result.ts";
 /** Package-private monotonic clock seam for execution accounting. */
-export type CheckExecutionClock = Readonly<{
-    now(): number;
-}>;
-export type CheckStartedFact = Readonly<{
-    checkId: string;
-    displayName: string;
-}>;
-export type CheckSettledFact = CheckStartedFact & Readonly<{
-    durationMs: number | null;
-    messages: readonly CheckMessage[];
-    outcome: CheckOutcome;
-    visibility: CheckVisibility;
-}>;
-type ResolvedCheckExecutionFacts = Readonly<{
-    readonly checkDurations: readonly import("../result.ts").CheckDuration[];
-    readonly checkMessages: readonly import("../result.ts").CheckRunMessage[];
-    readonly snapshot: import("../../check-settlement/facts.ts").CoreSnapshot;
-}>;
-export type ResolvedCheckExecution = (Readonly<{
-    readonly kind: "completed";
-}> & ResolvedCheckExecutionFacts) | (Readonly<{
-    readonly kind: "cancelled";
-}> & ResolvedCheckExecutionFacts);
-export interface CheckExecutionState extends CheckExecutionSettlementState {
-    readonly session: CoreCheckSession;
-}
-/**
- * Runs the already normalized executable Check collection through one generic
- * Task per Check. Graph validation happens before Core scopes or callbacks.
- */
-export declare function executeResolvedChecks(input: Readonly<{
+export type { CheckExecutionClock } from "./admitted-check-execution.ts";
+export type ResolvedCheckExecutionInput = Readonly<{
+    /** Complete prepared private policy handoff; public policy dispatch stays outside execution. */
+    readonly admissionPolicy?: AdmissionSelectionPolicy;
     readonly checks: readonly NormalizedCheck[];
     readonly maxParallel: number;
+    readonly resourceCapacities?: ResourceUnitMapping;
+    /** Product invocation identity；private direct-execution tests 使用稳定 fallback。 */
+    readonly invocationId?: string;
+    /** 冻结的 invocation paths；仅 private direct-execution tests 可以省略。 */
+    readonly paths?: ResolvedInvocationPaths;
     readonly project: CheckProjectContext;
     readonly signal: AbortSignal | undefined;
     readonly clock?: CheckExecutionClock;
+    /** Core-owner Check lifecycle channel. */
     readonly diagnosticLogger?: DiagnosticLogger;
-    readonly lifecycle?: CheckExecutionLifecycle;
-}>): Promise<ResolvedCheckExecution>;
-export {};
+    /** Scheduler-owner decision and summary channel. */
+    readonly schedulerDiagnosticLogger?: DiagnosticLogger;
+    /** Explicit enabled-only diagnostics handoff from the invocation output owner. */
+    readonly schedulerPerformanceDiagnostics?: SchedulerPerformanceDiagnosticsInput;
+    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;
+}>;
+/**
+ * Runs the already normalized executable Check collection through one generic
+ * Task per Check. Graph validation happens before Core scopes or callbacks.
+ */
+export declare function executeResolvedChecks(input: ResolvedCheckExecutionInput): Promise<ResolvedCheckExecution>;

package/types/project-run/check-execution/resolved-execution-result.d.ts

@@ -0,0 +1,21 @@
+import type { CoreSnapshot } from "../../check-settlement/facts.ts";
+import type { SchedulerMeasurementContext } from "../../project-definition/project-definition.ts";
+import type { CheckDuration, CheckRunMessage } from "../result.ts";
+type ResolvedCheckExecutionFacts = Readonly<{
+    readonly checkDurations: readonly CheckDuration[];
+    readonly checkMessages: readonly CheckRunMessage[];
+    readonly snapshot: CoreSnapshot;
+    /** Product-private terminal Scheduler facts; never projected into RunResult. */
+    readonly terminalSchedulerMeasurement?: SchedulerMeasurementContext;
+}>;
+/** Private terminal result passed from Check execution to the invocation boundary. */
+export type ResolvedCheckExecution = (Readonly<{
+    /** Private effective selection shared with invocation-level aggregation. */
+    readonly effectiveCheckIds: readonly string[];
+    readonly kind: "completed";
+}> & ResolvedCheckExecutionFacts) | (Readonly<{
+    readonly kind: "cancelled";
+}> & ResolvedCheckExecutionFacts) | (Readonly<{
+    readonly kind: "admission-policy-failed";
+}> & ResolvedCheckExecutionFacts);
+export {};

package/types/project-run/check-execution/scheduled-check-run.d.ts

@@ -0,0 +1,10 @@
+/** Maps normalized Checks into the Scheduler's opaque Task execute contract. */
+import { runTaskGraph } from "../task-scheduler/scheduler.ts";
+import { type CheckExecutionState } from "./execution-settlement.ts";
+import type { FlagControlSettlement } from "./flag-controls.ts";
+import type { ResolvedCheckExecutionInput } from "./resolved-checks.ts";
+export declare function runScheduledChecks(input: Readonly<{
+    readonly execution: ResolvedCheckExecutionInput;
+    readonly flagControlSettlements: readonly FlagControlSettlement[];
+    readonly state: CheckExecutionState;
+}>): Promise<Awaited<ReturnType<typeof runTaskGraph<boolean>>>>;

package/types/project-run/check-execution/terminal-result.d.ts

@@ -1,13 +1,20 @@
 import type { CheckMessage } from "../../check/check.ts";
+import type { HandoffProviderIdentity } from "../../check/handoff-provider-identity.ts";
 /**
  * A terminal callback result split into the Core-owned four-state result and
  * detached presentation-only messages. The caller must still pass `result` to
  * 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;
@@ -23,5 +30,10 @@ type StrippedTerminalResult = Readonly<{
  * closed author result. Any malformed attachment rejects the whole value so a
  * valid prefix can never escape into lifecycle or Run result state.
  */
-export declare function parseCheckTerminalResult(value: unknown): ParsedCheckTerminalResult | undefined;
+export declare function parseCheckTerminalResult(value: unknown, handoffIdentity: HandoffProviderIdentity | undefined): ParsedCheckTerminalResult | undefined;
+/**
+ * A declared provider result can contain an invocation-private reference. Diagnostics
+ * retain only its parsed terminal result, and represent malformed values as null.
+ */
+export declare function diagnosticCallbackResult(value: unknown, handoffIdentity: HandoffProviderIdentity | undefined): unknown;
 export {};

package/types/project-run/{completion.d.ts → completion/completion.d.ts}

@@ -1,10 +1,10 @@
-import { type CheckDuration, type CheckRunMessage, type NonConfigurationRunResult } from "./result.ts";
-import type { CheckAggregate } from "./controls/contract.ts";
-import type { Invocation } from "./invocation.ts";
-import type { CoreSnapshot } from "../check-settlement/facts.ts";
+import { type CheckDuration, type CheckRunMessage, type NonConfigurationRunResult } from "../result.ts";
+import type { CheckAggregate } from "../controls/contract.ts";
+import type { Invocation } from "../invocation/run.ts";
+import type { CoreSnapshot } from "../../check-settlement/facts.ts";
 /** 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;
@@ -12,3 +12,5 @@ export type CoreExecution = Readonly<{
 export declare function completeInvocation(invocation: Invocation, core: CoreExecution): NonConfigurationRunResult;
 /** Closes diagnostic logging and applies final output priority to a non-configuration candidate. */
 export declare function finalizeInvocation(invocation: Invocation, candidate: NonConfigurationRunResult): NonConfigurationRunResult;
+/** Closes invocation-owned writers after aggregation rejects without fabricating a terminal Run result. */
+export declare function closeAggregationFailure(invocation: Invocation): void;

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

@@ -1,6 +1,6 @@
-import type { ProjectOutputs } from "../project-definition/project-definition.ts";
-import type { TrustedPublicationModelV4 } from "../machine-output/v4/publication-model.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 type { OutputStatuses } from "../outputs/status.ts";
 /** Publishes an already-trusted v4 model as the Run-owned machine output. */
 export declare function publishMachineOutput(input: Readonly<{
     readonly configuration: ProjectOutputs["machinePublication"];

package/types/project-run/completion/result-resolver.d.ts

@@ -0,0 +1,4 @@
+import { type RunOutputStatuses } from "../outputs/status.ts";
+import { type NonConfigurationRunResult } from "../result.ts";
+/** Resolves a terminal candidate against the output statuses after all owners have closed. */
+export declare function resolveFinalRunResult(candidate: NonConfigurationRunResult, outputs: RunOutputStatuses): NonConfigurationRunResult;

package/types/project-run/controls/contract.d.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/types/project-run/controls/outputs-override-validation.d.ts

@@ -1,3 +1,4 @@
 import type { RunControls } from "./contract.ts";
+import type { RunControlValidationResult } from "./validation-result.ts";
 /** Parses invocation-local outputs without changing Definition defaults. */
-export declare function parseOutputsOverride(value: unknown): RunControls["outputs"] | undefined;
+export declare function parseOutputsOverride(value: unknown): RunControlValidationResult<RunControls["outputs"]>;

package/types/project-run/controls/validation-result.d.ts

@@ -1,9 +1,17 @@
-/** Diagnostic emitted when one invocation control is not a closed supported value. */
-export interface RunControlDiagnostic {
+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" | "unknown-key";
-}
+} & ({
+    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<{
     readonly ok: true;

package/types/project-run/diagnostic-logging/logger.d.ts

@@ -1,16 +1,31 @@
 import type { CheckExecutionClock } from "../check-execution/resolved-checks.ts";
 export { summarizeDiagnosticValue } from "./diagnostic-detail-rendering.ts";
-/** Product-private observation written synchronously at the fact owner. */
+export declare const DIAGNOSTIC_CHANNELS: readonly ["core", "scheduler"];
+export type DiagnosticChannel = (typeof DIAGNOSTIC_CHANNELS)[number];
+export type DiagnosticChannelStatus = "disabled" | "failed" | "succeeded";
+/** Product-private observation written synchronously at its output owner. */
 export interface DiagnosticObservation {
+    /** Router-owned correlation, added before any channel write and never authored by Check code. */
+    readonly correlation?: Readonly<{
+        readonly elapsedMs: number;
+        readonly invocationId: string;
+        readonly sequence: number;
+    }>;
     readonly details?: unknown;
     readonly event: string;
     readonly tags: readonly string[];
 }
-/** Product-private invocation logger; its failures never escape lifecycle owners. */
+/** One channel writer. Its failures never escape the lifecycle owner that emits an observation. */
 export interface DiagnosticLogger {
-    close(): "disabled" | "failed" | "succeeded";
+    close(): DiagnosticChannelStatus;
     observe(observation: DiagnosticObservation): void;
 }
+/** The invocation-local router is the sole Product correlation and channel-routing owner. */
+export interface DiagnosticLoggingRouter {
+    readonly core: DiagnosticLogger;
+    readonly scheduler: DiagnosticLogger;
+    close(): Readonly<Record<DiagnosticChannel, DiagnosticChannelStatus>>;
+}
 /** A bounded, descriptor-safe description for normal diagnostic payloads. */
 export type DiagnosticValueSummary = Readonly<{
     readonly availability: "available";
@@ -22,12 +37,27 @@ export type DiagnosticValueSummary = Readonly<{
     readonly availability: "unavailable";
     readonly reason: string;
 }>;
-/** Test-only construction seam; Product invocation owns its lifecycle and output mapping. */
+/** Test-only construction seam; invocation construction owns all three channel lifecycles. */
 export type DiagnosticLoggerFactory = (input: Readonly<{
     readonly clock: CheckExecutionClock;
     readonly enabled: boolean;
     readonly file: string | null;
 }>) => DiagnosticLogger;
+/**
+ * Creates one direct channel writer. The invocation router normally supplies correlation; retaining this
+ * construction function keeps focused writer tests independent of multi-channel invocation wiring.
+ */
 export declare const createDiagnosticLogger: DiagnosticLoggerFactory;
+/**
+ * Builds the minimal owner-neutral router. It has no subscriber registry: the Product owners are
+ * explicit fields, each writer is isolated, and one shared sequence/clock is assigned before delegation.
+ */
+export declare function createDiagnosticLoggingRouter(input: Readonly<{
+    readonly clock: CheckExecutionClock;
+    readonly coreFile: string | null;
+    readonly factory: DiagnosticLoggerFactory;
+    readonly invocationId: string;
+    readonly schedulerFile: string | null;
+}>): DiagnosticLoggingRouter;
 /** Builds one immutable set of human-filterable diagnostic labels. */
 export declare function diagnosticTags(...tags: readonly string[]): readonly string[];

package/types/project-run/diagnostic-logging/observation-rendering.d.ts

@@ -0,0 +1,7 @@
+import type { DiagnosticObservation } from "./logger.ts";
+export declare function renderDiagnosticObservation(input: Readonly<{
+    readonly elapsedMs: number;
+    readonly invocationId: string | undefined;
+    readonly observation: DiagnosticObservation;
+    readonly sequence: number;
+}>): string;

package/types/project-run/invocation/candidate.d.ts

@@ -0,0 +1,12 @@
+import type { CheckAggregation } from "../controls/contract.ts";
+import type { Invocation } from "./run.ts";
+import { type NonConfigurationRunResult } from "../result.ts";
+import type { ResolvedCheckExecution } from "../check-execution/resolved-execution-result.ts";
+export type ResolvedExecutionCandidateInput = Readonly<{
+    readonly aggregation: CheckAggregation | undefined;
+    readonly executed: ResolvedCheckExecution;
+    readonly executionStartedAt: number;
+    readonly invocation: Invocation;
+}>;
+/** Maps a sealed Scheduler result into the Run-owned candidate before terminal output closure. */
+export declare function mapResolvedExecutionToRunCandidate(input: ResolvedExecutionCandidateInput): NonConfigurationRunResult;

package/types/project-run/invocation/candidates.d.ts

@@ -0,0 +1,8 @@
+import { type NonConfigurationRunResult, type RunDiagnostic } from "../result.ts";
+import type { Invocation } from "./run.ts";
+/** Records a pre-execution cancellation as the Run-owned candidate result. */
+export declare function cancelledBeforeExecution(invocation: Invocation, phase: "pre-work" | "planning"): NonConfigurationRunResult;
+/** Constructs the planning failure candidate after the static graph has been rejected. */
+export declare function planningResult(invocation: Invocation, code: Extract<RunDiagnostic["code"], "task-graph-invalid">): NonConfigurationRunResult;
+/** Constructs a pre-settlement execution failure without revising existing output facts. */
+export declare function executionResult(invocation: Invocation, code: Extract<RunDiagnostic["code"], "admission-strategy-preparation-failed" | "task-engine-failed">): NonConfigurationRunResult;

package/types/project-run/{invocation-creation.d.ts → invocation/creation.d.ts}

@@ -1,6 +1,6 @@
-import { type DefinitionWarning, type NormalizedProjectDefinition, type ProjectDefinition } from "../project-definition/project-definition.ts";
-import type { RunControls } from "./controls/contract.ts";
-import type { Invocation, RunInvocationDependencies } from "./invocation.ts";
+import { type DefinitionWarning, type NormalizedProjectDefinition, type ProjectDefinition } from "../../project-definition/project-definition.ts";
+import type { RunControls } from "../controls/contract.ts";
+import type { Invocation, RunInvocationDependencies } from "./run.ts";
 export interface InvocationCreationInput {
     readonly controls: RunControls;
     readonly definition: ProjectDefinition;