@zxyycom/vibe-check 0.0.1 → 0.0.2

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

@@ -1,7 +1,7 @@
 import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.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 { CheckExecutionLifecycle } from "./lifecycle.ts";
 import type { executeCheckCallback } from "./callback.ts";
 export type CheckIdentity = Readonly<{
     readonly checkId: string;
@@ -13,10 +13,13 @@ export interface SettledCheckFacts {
     readonly messages: readonly CheckMessage[];
 }
 export type CheckExecutionSettlementState = Readonly<{
+    readonly session: CoreCheckSession;
     readonly diagnosticLogger: DiagnosticLogger | undefined;
     readonly lifecycle: CheckExecutionLifecycle | undefined;
     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);
 }
@@ -36,6 +39,6 @@ export declare function recordSettledCheck(input: Readonly<{
     readonly durationMs: number | null;
     readonly messages: readonly CheckMessage[];
     readonly outcome: CheckOutcome;
-    readonly phase: "execution" | "preflight";
+    readonly phase: "control" | "dependency" | "execution" | "preflight";
     readonly state: CheckExecutionSettlementState;
 }>): void;

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" | "visibility">;
+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,20 @@
+import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.ts";
+import type { CoreRecord } from "../../check-settlement/facts.ts";
+/** Private Run handoff for Check lifecycle presentation and accounting. */
+export type CheckExecutionLifecycle = Readonly<{
+    /** Fires after the invocation-wide flag-control phase and before Scheduler execution starts. */
+    readonly flagControlCompleted: () => void;
+    readonly started: (fact: CheckStartedFact) => void;
+    readonly settled: (fact: CheckSettledFact) => void;
+}>;
+export type CheckStartedFact = Readonly<{
+    checkId: string;
+    displayName: string;
+}>;
+export type CheckSettledFact = CheckStartedFact & Readonly<{
+    durationMs: number | null;
+    messages: readonly CheckMessage[];
+    records: readonly CoreRecord[];
+    outcome: CheckOutcome;
+    visibility: CheckVisibility;
+}>;

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.d.ts

@@ -18,10 +18,11 @@ export type BlockedCheckPreflightResolution = Readonly<{
     readonly outcome: CheckOutcome;
 }>;
 export type CheckPreflightResolution = ReadyCheckPreflightResolution | BlockedCheckPreflightResolution;
-/** Completes the sequential invocation-wide barrier before any Check enters the Task graph. */
-export declare function prepareChecks(input: Readonly<{
-    readonly checks: readonly NormalizedCheck[];
-    readonly diagnosticLogger?: DiagnosticLogger;
+type PrepareCheckInput = Readonly<{
+    readonly check: NormalizedCheck;
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
     readonly signal: AbortSignal | undefined;
-}>): Promise<readonly CheckPreflightResolution[]>;
+}>;
+/** Resolves one Check's task-local preparation after Scheduler admission. */
+export declare function prepareCheck(input: PrepareCheckInput): Promise<CheckPreflightResolution>;
 export {};

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

@@ -1,51 +1,45 @@
-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 { CheckProjectContext } from "../../check/check.ts";
+import type { NormalizedCheck, SchedulerMeasurementHook } 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 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 { 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 } from "./lifecycle.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<{
+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;
+    /** Scheduler-owner decision and summary channel. */
+    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;
-}>): Promise<ResolvedCheckExecution>;
+    /** 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>;
 export {};

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

@@ -1,7 +1,7 @@
-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;

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,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/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-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;

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

@@ -0,0 +1,40 @@
+import type { DiagnosticChannel } from "../diagnostic-logging/logger.ts";
+import type { DiagnosticLogFileNaming } from "../controls/contract.ts";
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+/**
+ * Invocation owner 的 absolute paths；刻意排除 caller-owned cross-Run state、cache storage 和
+ * external-tool workspace。
+ */
+export type ResolvedInvocationPaths = Readonly<{
+    /** Check-local absolute directories；保持私有，避免披露 sibling capability。 */
+    readonly checkArtifactDirectories: readonly ResolvedCheckArtifactDirectory[];
+    /** caller 选择的 Check-owned invocation artifact absolute base；未配置时为 `null`。 */
+    readonly checkArtifactBaseDirectory: string | null;
+    /** 按 owner channel 分开的 diagnostic absolute targets。 */
+    readonly diagnosticLoggingFiles: Readonly<Record<DiagnosticChannel, string | null>>;
+    /** 按既有 RunResult-relative contract 投影的 diagnostic channel files。 */
+    readonly diagnosticLoggingReadbackFiles: Readonly<Record<DiagnosticChannel, string | null>>;
+    /** 本次 invocation 的 machine publisher absolute target。 */
+    readonly machinePublicationDirectory: string;
+    /** caller 为本 Run 指定的 progress transcript target；不设置则只保留 terminal。 */
+    readonly progressLogFile: string | null;
+    /** 每个 callback 共享的 absolute effective project root。 */
+    readonly projectRoot: string;
+}>;
+/** 在任何 author callback 前恰好一次解析全部 Product-owned invocation target。 */
+export declare function resolveInvocationPaths(input: Readonly<{
+    readonly checkArtifactBaseDirectory: string | undefined;
+    readonly checkIds: readonly string[];
+    readonly diagnosticLogFileNaming: DiagnosticLogFileNaming;
+    readonly diagnosticLogSuffix: string | undefined;
+    readonly outputConfiguration: ProjectOutputs;
+    readonly progressLogFile: string | undefined;
+    readonly projectRoot: string;
+}>): ResolvedInvocationPaths;
+type ResolvedCheckArtifactDirectory = Readonly<{
+    readonly checkId: string;
+    readonly directory: string;
+}>;
+/** 只返回当前 Check-local artifact directory，不向 callback 暴露 sibling directories。 */
+export declare function artifactDirectoryForCheck(paths: ResolvedInvocationPaths, checkId: string): string | null;
+export {};

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

@@ -0,0 +1,11 @@
+import type { CoreSnapshot } from "../../check-settlement/facts.ts";
+import type { CheckExecutionClock } from "../check-execution/resolved-checks.ts";
+/** Forms the terminal progress counters without changing Core Check facts. */
+export declare function outcomeCounts(snapshot: CoreSnapshot): Readonly<{
+    readonly failed: number;
+    readonly notApplicable: number;
+    readonly passed: number;
+    readonly unavailable: number;
+}>;
+/** Converts the invocation monotonic clock into a safe progress duration. */
+export declare function elapsedSince(startedAt: number, clock: CheckExecutionClock): number;

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

@@ -0,0 +1,43 @@
+import { type DefinitionWarning, type NormalizedProjectDefinition, type ProjectDefinition, type ResolvedProjectOutputs } from "../../project-definition/project-definition.ts";
+import type { RunControls } from "../controls/contract.ts";
+import { type AdmissionStrategyProviderFactory } from "../admission-strategy-provider/provider.ts";
+import { type CheckExecutionClock } from "../check-execution/resolved-checks.ts";
+import { type ProgressRefreshScheduler, type ProgressRendering, type ProgressWriterFactory } from "../progress-rendering/presentation.ts";
+import type { ResolvedInvocationPaths } from "./paths.ts";
+import { type RunResult } from "../result.ts";
+import { type DiagnosticLoggerFactory, type DiagnosticLoggingRouter } from "../diagnostic-logging/logger.ts";
+import type { OutputStatuses } from "../outputs/status.ts";
+export type Invocation = Readonly<{
+    /** Product-private test seam; package `run` never accepts a provider factory. */
+    readonly admissionStrategyProviderFactory: AdmissionStrategyProviderFactory | undefined;
+    readonly clock: CheckExecutionClock;
+    readonly controls: RunControls;
+    readonly declarativeFingerprint: string;
+    readonly definition: ProjectDefinition;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly diagnosticLogging: DiagnosticLoggingRouter;
+    /** Effective output selection, retained privately for enabled-only Scheduler diagnostics. */
+    readonly diagnosticLoggingEnabled: boolean;
+    readonly outputConfiguration: ResolvedProjectOutputs;
+    readonly outputs: OutputStatuses;
+    readonly invocationId: string;
+    readonly normalized: NormalizedProjectDefinition;
+    /** 本次 invocation 冻结的 Product-private output 与 Check artifact paths。 */
+    readonly paths: ResolvedInvocationPaths;
+    readonly progressRendering: ProgressRendering;
+    /** Immutable UTC instant captured for enabled diagnostic or machine output, otherwise `null`. */
+    readonly startedAtUtc: string | null;
+}>;
+export interface RunInvocationDependencies {
+    /** Product-private test seam for proving invocation lifecycle sequencing. */
+    readonly admissionStrategyProviderFactory?: AdmissionStrategyProviderFactory;
+    readonly clock?: CheckExecutionClock;
+    readonly progressRefreshScheduler?: ProgressRefreshScheduler;
+    readonly progressWriterFactory?: ProgressWriterFactory;
+    readonly diagnosticLoggerFactory?: DiagnosticLoggerFactory;
+    /** Test seam for the invocation's machine-readable wall-clock timestamp. */
+    readonly wallClock?: Readonly<{
+        now(): Date;
+    }>;
+}
+export declare function executeValidatedRun(definition: ProjectDefinition, controls: RunControls, definitionWarnings: readonly DefinitionWarning[], dependencies?: RunInvocationDependencies): Promise<RunResult>;

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

@@ -0,0 +1,16 @@
+import type { CheckProjectContext } from "../../check/check.ts";
+import type { PreparedAdmissionStrategy } from "../admission-strategy-provider/prepared-admission-strategy.ts";
+import type { ResolvedCheckExecution } from "../check-execution/resolved-execution-result.ts";
+import type { Invocation } from "./run.ts";
+import type { NonConfigurationRunResult } from "../result.ts";
+export type SchedulerExecution = ResolvedCheckExecution | Extract<NonConfigurationRunResult, {
+    readonly kind: "execution";
+}>;
+type SchedulerAdapterInput = Readonly<{
+    readonly invocation: Invocation;
+    readonly preparedStrategy: PreparedAdmissionStrategy;
+    readonly project: CheckProjectContext;
+}>;
+/** Bridges one prepared invocation to resolved Check execution and contains task-engine faults. */
+export declare function executeScheduler(input: SchedulerAdapterInput): Promise<SchedulerExecution>;
+export {};

package/types/project-run/outputs/configuration.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectDefinition, ResolvedProjectOutputs } from "../../project-definition/project-definition.ts";
+import type { RunControls } from "../controls/contract.ts";
+export declare function effectiveOutputs(definition: ProjectDefinition, controls: RunControls): ResolvedProjectOutputs;

package/types/project-run/outputs/status.d.ts

@@ -0,0 +1,48 @@
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+import { type DiagnosticChannel } from "../diagnostic-logging/logger.ts";
+/** 一项 Run-owned terminal output 或 measurement participant 的最终状态 readback。 */
+export interface RunOutputStatus {
+    /** effective configuration 是否启用该 participant；`false` 时 status 必为 `disabled`。 */
+    readonly enabled: boolean;
+    /** `disabled` 为未启用；`not-run` 为启用但未到达完成；`succeeded` 为完成，`failed` 为其 own I/O 或 hook failure。 */
+    readonly status: "disabled" | "failed" | "not-run" | "succeeded";
+}
+/** Product-owned 人读 diagnostic channel；即使 setup 失败也保留其 file readback。 */
+export interface RunDiagnosticLoggingChannelStatus extends RunOutputStatus {
+    /**
+     * 相对 effective project root 的 target readback；跨卷时可为 absolute path。disabled channel 为 `null`，
+     * enabled channel 即使 setup 失败也保留预先计算的 path。
+     */
+    readonly file: string | null;
+}
+/** diagnostic logging aggregate 及其各 owner channel 的最终状态 readback。 */
+export interface RunDiagnosticLoggingOutputStatus extends RunOutputStatus {
+    /** aggregate status 及每个 owner channel 的独立 readback；partial failure 可由此定位。 */
+    readonly channels: Readonly<Record<DiagnosticChannel, RunDiagnosticLoggingChannelStatus>>;
+}
+/** 配置有效后四个 terminal output participant 的独立最终状态。 */
+export interface RunOutputStatuses {
+    /** `run.json` 与 `records.ndjson` canonical publication 的状态。 */
+    readonly machinePublication: RunOutputStatus;
+    /** terminal progress 与可选 progress log tee 的状态。 */
+    readonly progressRendering: RunOutputStatus;
+    /** core 与 scheduler diagnostic channels 的 aggregate 状态。 */
+    readonly diagnosticLogging: RunDiagnosticLoggingOutputStatus;
+    /**
+     * Definition generic Hooks 与 prepared custom strategy 的 optional `complete` 所形成的 terminal participant
+     * 状态；它不能由 RunControls 注入或覆盖。
+     */
+    readonly measurementHooks: RunOutputStatus;
+}
+export interface OutputStatuses {
+    /** Enables a runtime-only terminal participant after successful preparation. */
+    readonly enableMeasurementHooks: () => void;
+    /** A diagnostic channel failure is isolated but updates the aggregate diagnostic output. */
+    readonly failedDiagnosticChannel: (channel: DiagnosticChannel) => void;
+    readonly failed: (output: keyof RunOutputStatuses) => void;
+    readonly succeededDiagnosticChannel: (channel: DiagnosticChannel) => void;
+    readonly succeeded: (output: keyof RunOutputStatuses) => void;
+    readonly value: () => RunOutputStatuses;
+}
+export declare function createOutputStatuses(configuration: ProjectOutputs, diagnosticLoggingFiles: Readonly<Record<DiagnosticChannel, string | null>>, initialMeasurementHooksEnabled: boolean): OutputStatuses;
+export declare function failedOutput(statuses: RunOutputStatuses): keyof RunOutputStatuses | undefined;