@zxyycom/vibe-check 0.0.1

package/types/project-definition/project-definition.d.ts

@@ -0,0 +1,88 @@
+import type { MeaninglessCheckWarning } from "./check-tree/authoring.ts";
+import type { CheckDescriptor } from "../check/descriptor.ts";
+import type { Check, CheckExecution, CheckPreflight, CheckVisibility } from "../check/check.ts";
+/** 一次 Project Run 的明确输出配置。 */
+export interface ProjectOutputs {
+    /** `run.json` 与 `records.ndjson` publication。 */
+    readonly machinePublication: Readonly<{
+        /** 相对目录以 project root 解析，默认 `artifacts/vibe-check`。 */
+        readonly directory: string;
+        /** `false` 时本次 Run 不发布 machine output。 */
+        readonly enabled: boolean;
+    }>;
+    /** 人读 progress rendering。 */
+    readonly progressRendering: Readonly<{
+        /** `false` 时不构造或写入 progress writer。 */
+        readonly enabled: boolean;
+    }>;
+    /** 仅供维护者读取的一次 invocation diagnostic log。 */
+    readonly diagnosticLogging: Readonly<{
+        /** 相对目录以 project root 解析，默认 `.log/vibe-check`。 */
+        readonly directory: string;
+        /** `false` 时不创建 diagnostic writer 或 file。 */
+        readonly enabled: boolean;
+    }>;
+}
+/** 定义级的 Check 调度预算。 */
+export interface SchedulerPolicy {
+    readonly maxParallel: number;
+}
+/** 已补齐默认 outputs、可交给 run 执行的项目定义。 */
+export interface ProjectDefinition {
+    readonly apiVersion: "1";
+    readonly checks: readonly Check[];
+    readonly outputs: ProjectOutputs;
+    readonly scheduler: SchedulerPolicy;
+}
+type ProjectDefinitionInput = Readonly<{
+    apiVersion?: "1";
+    checks?: readonly Check[];
+    outputs?: Partial<{
+        machinePublication: Partial<ProjectOutputs["machinePublication"]>;
+        progressRendering: Partial<ProjectOutputs["progressRendering"]>;
+        diagnosticLogging: Partial<ProjectOutputs["diagnosticLogging"]>;
+    }>;
+    scheduler?: Partial<SchedulerPolicy>;
+}>;
+export interface ProjectDefinitionDiagnostic {
+    readonly kind: "invalid-project-definition";
+    readonly path: string;
+    readonly reason: "invalid-value" | "unknown-key";
+}
+export type DefinitionWarning = MeaninglessCheckWarning;
+export type ProjectDefinitionValidationResult = Readonly<{
+    readonly ok: true;
+    readonly value: ProjectDefinition;
+    readonly warnings: readonly DefinitionWarning[];
+} | {
+    readonly ok: false;
+    readonly error: ProjectDefinitionDiagnostic;
+}>;
+export interface NormalizedCheckDeclaration {
+    readonly definition: CheckDescriptor;
+    readonly dependsOn: readonly string[];
+    readonly maxParallel: number;
+    readonly mutex: readonly string[];
+    readonly options: object;
+    readonly visibility: CheckVisibility;
+}
+export interface NormalizedCheck extends NormalizedCheckDeclaration {
+    readonly execution: CheckExecution;
+    readonly preflight?: CheckPreflight;
+}
+export interface DeclarativeProjectSnapshot {
+    readonly apiVersion: "1";
+    readonly checks: readonly NormalizedCheckDeclaration[];
+    readonly outputs: ProjectOutputs;
+    readonly scheduler: SchedulerPolicy;
+}
+export interface NormalizedProjectDefinition {
+    readonly checks: readonly NormalizedCheck[];
+    readonly declarative: DeclarativeProjectSnapshot;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+}
+/** 使用 Product 默认输出创建普通 Project Definition。 */
+export declare function defineConfig<const T extends ProjectDefinitionInput>(value: T & Record<Exclude<keyof T, keyof ProjectDefinitionInput>, never>): ProjectDefinition;
+export declare function normalizeProjectDefinition(definition: ProjectDefinition): NormalizedProjectDefinition;
+export declare function createDeclarativeFingerprint(snapshot: DeclarativeProjectSnapshot): string;
+export {};

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

@@ -0,0 +1,7 @@
+import type { RunControlValidationResult } from "./controls/validation-result.ts";
+import type { CheckAggregate, CheckAggregation } from "./controls/contract.ts";
+import type { CoreSnapshot } from "../check-settlement/facts.ts";
+/** Validates that aggregation selects only normalized executable Check IDs. */
+export declare function validateCheckAggregationSelection(aggregation: CheckAggregation | undefined, checkIds: readonly string[]): RunControlValidationResult<CheckAggregation | undefined>;
+/** Derives one explicit consumer-selected aggregate from settled Check statuses only. */
+export declare function aggregateCheckOutcomes(snapshot: CoreSnapshot, aggregation: CheckAggregation): CheckAggregate;

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

@@ -0,0 +1,24 @@
+import type { CheckDependencies, CheckOutcome, CheckProjectContext } from "../../check/check.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { type TrustedCheckScope } from "../../check-settlement/session.ts";
+import { type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+export type CallbackExecution = Readonly<{
+    /** Raw author result; Core owns its sole validation and canonicalization. */
+    readonly source: "author";
+    readonly result: unknown;
+} | {
+    /** Only callback containment may create a Product-controlled outcome. */
+    readonly source: "product";
+    readonly result: CheckOutcome;
+}>;
+interface CheckCallbackInput {
+    readonly check: NormalizedCheck;
+    readonly dependencies: CheckDependencies;
+    readonly diagnosticLogger?: DiagnosticLogger;
+    readonly project: CheckProjectContext;
+    readonly scope: TrustedCheckScope;
+    readonly signal: AbortSignal;
+}
+/** Runs one trusted callback and closes its Check-owned reporter before return. */
+export declare function executeCheckCallback(input: CheckCallbackInput): Promise<CallbackExecution>;
+export {};

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

@@ -0,0 +1,9 @@
+import type { CheckDependencies } from "../../check/check.ts";
+import type { CoreCheckSession } from "../../check-settlement/session.ts";
+import { type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+export declare function createCheckDependencies(input: Readonly<{
+    readonly checkId: string;
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly directDependencyIds: readonly string[];
+    readonly session: CoreCheckSession;
+}>): CheckDependencies;

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

@@ -0,0 +1,18 @@
+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";
+/** 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 state: CheckExecutionState;
+}>): ResolvedCheckExecution;
+export declare function closeCancelledExecution(input: Readonly<{
+    readonly normalizedChecks: readonly NormalizedCheck[];
+    readonly preparedChecks: readonly PreparedCheck[];
+    readonly state: CheckExecutionState;
+}>): ResolvedCheckExecution;
+export declare function checkIdentity(check: Pick<NormalizedCheck, "definition" | "visibility">): CheckIdentity;
+export declare function trustedFailure(error: unknown): CheckExecutionInvariantFailure;

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

@@ -0,0 +1,41 @@
+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 { executeCheckCallback } from "./callback.ts";
+export type CheckIdentity = Readonly<{
+    readonly checkId: string;
+    readonly displayName: string;
+    readonly visibility: CheckVisibility;
+}>;
+export interface SettledCheckFacts {
+    readonly durationMs: number | null;
+    readonly messages: readonly CheckMessage[];
+}
+export type CheckExecutionSettlementState = Readonly<{
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly lifecycle: CheckExecutionLifecycle | undefined;
+    readonly settledFactsByCheckId: Map<string, SettledCheckFacts>;
+}>;
+export declare class CheckExecutionInvariantFailure extends Error {
+    constructor(message: string);
+}
+export declare function settleCallback(input: Readonly<{
+    readonly callback: Awaited<ReturnType<typeof executeCheckCallback>>;
+    readonly checkId: string;
+    readonly diagnosticLogger: DiagnosticLogger | undefined;
+    readonly preflightMessages: readonly CheckMessage[];
+    readonly scope: ReturnType<CoreCheckSession["openCheckScope"]>;
+}>): Readonly<{
+    readonly messages: readonly CheckMessage[];
+    readonly outcome: CheckOutcome;
+}>;
+/** 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 state: CheckExecutionSettlementState;
+}>): void;

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

@@ -0,0 +1,3 @@
+import type { CheckMessage } from "../../check/check.ts";
+/** 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

@@ -0,0 +1,10 @@
+import type { TaskGraph } from "../task-scheduler/graph.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.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;

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

@@ -0,0 +1,23 @@
+import type { CheckMessage } from "../../check/check.ts";
+export type ParsedCheckPreflightResult = Readonly<{
+    readonly status: "success";
+    readonly preparedOptions: unknown;
+    readonly messages: readonly CheckMessage[];
+}> | Readonly<{
+    readonly status: "failure";
+    readonly action: "block";
+    readonly reason: {
+        readonly code: string;
+    };
+    readonly messages: readonly CheckMessage[];
+}> | Readonly<{
+    readonly status: "failure";
+    readonly action: "continue";
+    readonly fallback: unknown;
+    readonly reason: {
+        readonly code: string;
+    };
+    readonly messages: readonly CheckMessage[];
+}>;
+/** Parses the closed result vocabulary returned by one trusted Check preflight. */
+export declare function parseCheckPreflightResult(value: unknown): ParsedCheckPreflightResult | undefined;

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

@@ -0,0 +1,27 @@
+import type { CheckMessage, CheckOutcome } 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" | "preflight"> & Readonly<{
+    readonly options: object;
+    readonly preflightMessages: readonly CheckMessage[];
+}>;
+type BlockedCheck = Pick<NormalizedCheck, "definition" | "visibility"> & Readonly<{
+    readonly preflightMessages: readonly CheckMessage[];
+}>;
+export type ReadyCheckPreflightResolution = Readonly<{
+    readonly kind: "ready";
+    readonly check: PreparedCheck;
+}>;
+export type BlockedCheckPreflightResolution = Readonly<{
+    readonly kind: "blocked";
+    readonly check: BlockedCheck;
+    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;
+    readonly signal: AbortSignal | undefined;
+}>): Promise<readonly CheckPreflightResolution[]>;
+export {};

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

@@ -0,0 +1,51 @@
+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;
+}>;
+/** 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<{
+    readonly checks: readonly NormalizedCheck[];
+    readonly maxParallel: number;
+    readonly project: CheckProjectContext;
+    readonly signal: AbortSignal | undefined;
+    readonly clock?: CheckExecutionClock;
+    readonly diagnosticLogger?: DiagnosticLogger;
+    readonly lifecycle?: CheckExecutionLifecycle;
+}>): Promise<ResolvedCheckExecution>;
+export {};

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

@@ -0,0 +1,27 @@
+import type { CheckMessage } from "../../check/check.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 messages: readonly CheckMessage[];
+    readonly result: StrippedTerminalResult;
+}
+type StrippedTerminalResult = Readonly<{
+    readonly status: "passed" | "failed";
+    readonly data: unknown;
+}> | Readonly<{
+    readonly status: "not-applicable";
+    readonly reason?: unknown;
+}> | Readonly<{
+    readonly status: "unavailable";
+    readonly reason: unknown;
+}>;
+/**
+ * Safely removes an optional terminal-message attachment from an otherwise
+ * 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 {};

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

@@ -0,0 +1,14 @@
+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";
+/** Settled Check facts consumed by completion and output publication. */
+export type CoreExecution = Readonly<{
+    readonly aggregate: CheckAggregate | null;
+    readonly checkDurations: readonly CheckDuration[];
+    readonly checkMessages: readonly CheckRunMessage[];
+    readonly snapshot: CoreSnapshot;
+}>;
+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;

package/types/project-run/controls/contract.d.ts

@@ -0,0 +1,24 @@
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+/** 单次 run 调用的闭合上下文与 output override；Project Definition 保持为 authored input。 */
+export interface RunControls {
+    readonly checkAggregation?: CheckAggregation;
+    /** 仅为本次调用覆盖 Run-owned outputs。 */
+    readonly outputs?: Partial<{
+        machinePublication: Partial<ProjectOutputs["machinePublication"]>;
+        progressRendering: Partial<ProjectOutputs["progressRendering"]>;
+        diagnosticLogging: Partial<ProjectOutputs["diagnosticLogging"]>;
+    }>;
+    readonly flags?: readonly string[];
+    readonly projectRoot?: string;
+    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";
+}
+/** `CheckAggregation` 计算出的 invocation 级结果。 */
+export type CheckAggregate = "passed" | "failed" | "not-applicable" | "unavailable";

package/types/project-run/controls/outputs-override-validation.d.ts

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

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

@@ -0,0 +1,14 @@
+/** 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";
+}
+/** Closed validation result for a Run-owned invocation control. */
+export type RunControlValidationResult<T> = Readonly<{
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: RunControlDiagnostic;
+}>;

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

@@ -0,0 +1,3 @@
+import type { RunControlValidationResult } from "./validation-result.ts";
+import type { RunControls } from "./contract.ts";
+export declare function validateRunControls(value?: unknown): RunControlValidationResult<RunControls>;

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

@@ -0,0 +1,11 @@
+import type { DiagnosticValueSummary } from "./logger.ts";
+export declare function summarizeDiagnosticValue(value: unknown): DiagnosticValueSummary;
+export declare function renderSafeDiagnosticDetail(value: unknown): DetailRendering;
+type DetailRendering = Readonly<{
+    readonly ok: true;
+    readonly text: string;
+}> | Readonly<{
+    readonly ok: false;
+    readonly reason: string;
+}>;
+export {};

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

@@ -0,0 +1,33 @@
+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 interface DiagnosticObservation {
+    readonly details?: unknown;
+    readonly event: string;
+    readonly tags: readonly string[];
+}
+/** Product-private invocation logger; its failures never escape lifecycle owners. */
+export interface DiagnosticLogger {
+    close(): "disabled" | "failed" | "succeeded";
+    observe(observation: DiagnosticObservation): void;
+}
+/** A bounded, descriptor-safe description for normal diagnostic payloads. */
+export type DiagnosticValueSummary = Readonly<{
+    readonly availability: "available";
+    readonly bytes: number;
+    readonly items?: number;
+    readonly keys?: number;
+    readonly shape: "array" | "boolean" | "null" | "number" | "object" | "string";
+}> | Readonly<{
+    readonly availability: "unavailable";
+    readonly reason: string;
+}>;
+/** Test-only construction seam; Product invocation owns its lifecycle and output mapping. */
+export type DiagnosticLoggerFactory = (input: Readonly<{
+    readonly clock: CheckExecutionClock;
+    readonly enabled: boolean;
+    readonly file: string | null;
+}>) => DiagnosticLogger;
+export declare const createDiagnosticLogger: DiagnosticLoggerFactory;
+/** Builds one immutable set of human-filterable diagnostic labels. */
+export declare function diagnosticTags(...tags: readonly string[]): readonly string[];

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

@@ -0,0 +1,12 @@
+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";
+export interface InvocationCreationInput {
+    readonly controls: RunControls;
+    readonly definition: ProjectDefinition;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly dependencies: RunInvocationDependencies;
+    readonly normalized: NormalizedProjectDefinition;
+}
+/** Creates immutable invocation-owned output state before any planning or execution work. */
+export declare function createInvocation(input: InvocationCreationInput): Invocation;

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

@@ -0,0 +1,34 @@
+import { type DefinitionWarning, type NormalizedProjectDefinition, type ProjectDefinition } from "../project-definition/project-definition.ts";
+import type { RunControls } from "./controls/contract.ts";
+import { type CheckExecutionClock } from "./check-execution/resolved-checks.ts";
+import { type ProgressRefreshScheduler, type ProgressRendering, type ProgressWriterFactory } from "./progress-rendering/presentation.ts";
+import { type RunResult } from "./result.ts";
+import { type DiagnosticLogger, type DiagnosticLoggerFactory } from "./diagnostic-logging/logger.ts";
+import type { OutputStatuses } from "./output-status.ts";
+export type Invocation = Readonly<{
+    readonly clock: CheckExecutionClock;
+    readonly controls: RunControls;
+    readonly declarativeFingerprint: string;
+    readonly definition: ProjectDefinition;
+    readonly definitionWarnings: readonly DefinitionWarning[];
+    readonly diagnosticLogger: DiagnosticLogger;
+    readonly outputConfiguration: ProjectDefinition["outputs"];
+    readonly outputs: OutputStatuses;
+    readonly invocationId: string;
+    readonly normalized: NormalizedProjectDefinition;
+    readonly progressRendering: ProgressRendering;
+    readonly projectRoot: string;
+    /** Immutable UTC instant captured for enabled diagnostic or machine output, otherwise `null`. */
+    readonly startedAtUtc: string | null;
+}>;
+export interface RunInvocationDependencies {
+    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/machine-publication.d.ts

@@ -0,0 +1,10 @@
+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";
+/** Publishes an already-trusted v4 model as the Run-owned machine output. */
+export declare function publishMachineOutput(input: Readonly<{
+    readonly configuration: ProjectOutputs["machinePublication"];
+    readonly statuses: OutputStatuses;
+    readonly model: TrustedPublicationModelV4;
+    readonly directory: string;
+}>): boolean;

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

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

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

@@ -0,0 +1,21 @@
+import type { ProjectOutputs } from "../project-definition/project-definition.ts";
+export interface RunOutputStatus {
+    readonly enabled: boolean;
+    readonly status: "disabled" | "failed" | "not-run" | "succeeded";
+}
+export interface RunDiagnosticLoggingOutputStatus extends RunOutputStatus {
+    /** Project-root-relative target when enabled, otherwise `null`. */
+    readonly file: string | null;
+}
+export interface RunOutputStatuses {
+    readonly machinePublication: RunOutputStatus;
+    readonly progressRendering: RunOutputStatus;
+    readonly diagnosticLogging: RunDiagnosticLoggingOutputStatus;
+}
+export interface OutputStatuses {
+    readonly failed: (output: keyof RunOutputStatuses) => void;
+    readonly succeeded: (output: keyof RunOutputStatuses) => void;
+    readonly value: () => RunOutputStatuses;
+}
+export declare function createOutputStatuses(configuration: ProjectOutputs, diagnosticLoggingFile: string | null): OutputStatuses;
+export declare function failedOutput(statuses: RunOutputStatuses): keyof RunOutputStatuses | undefined;

package/types/project-run/progress-rendering/presentation.d.ts

@@ -0,0 +1,28 @@
+import type { CheckExecutionLifecycle } from "../check-execution/resolved-checks.ts";
+import { type ProgressClock, type ProgressOutcomeCounts, type ProgressWriter } from "./renderer.ts";
+import type { ProjectOutputs } from "../../project-definition/project-definition.ts";
+import type { OutputStatuses } from "../output-status.ts";
+export interface ProgressRendering {
+    readonly final: (input: ProgressFinalFeedback) => void;
+    readonly lifecycle: CheckExecutionLifecycle;
+    readonly prepared: (totalChecks: number) => void;
+}
+export interface ProgressFinalFeedback {
+    readonly counts: ProgressOutcomeCounts;
+    readonly elapsedMs: number;
+    readonly execution: "cancelled" | "completed";
+}
+export type ProgressWriterFactory = () => ProgressWriter;
+export interface ProgressRefreshSchedule {
+    cancel(): void;
+}
+export interface ProgressRefreshScheduler {
+    schedule(refresh: () => void, intervalMs: number): ProgressRefreshSchedule;
+}
+export interface ProgressRenderingDependencies {
+    readonly clock?: ProgressClock;
+    readonly refreshScheduler?: ProgressRefreshScheduler;
+    readonly writerFactory?: ProgressWriterFactory;
+}
+/** Owns progress writer lifecycle and rendering; failed writers are permanently muted. */
+export declare function createProgressRendering(configuration: ProjectOutputs["progressRendering"], statuses: OutputStatuses, dependencies?: ProgressRenderingDependencies): ProgressRendering;

package/types/project-run/progress-rendering/renderer-formatting.d.ts

@@ -0,0 +1,23 @@
+import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { ProgressFeedback } from "./renderer.ts";
+export declare function formatRunningRow(input: Readonly<{
+    readonly displayIndex: number;
+    readonly displayName: string;
+    readonly elapsedMs: number | null;
+    readonly totalChecks: number;
+}>): string;
+export declare function shouldPresentSettledFeedback(feedback: Extract<ProgressFeedback, {
+    readonly kind: "settled";
+}>): boolean;
+export declare function formatSettledBlock(input: Readonly<{
+    readonly completionOrdinal: number;
+    readonly displayName: string;
+    readonly durationMs: number | null;
+    readonly messages: readonly CheckMessage[];
+    readonly outcome: CheckOutcome;
+    readonly totalChecks: number;
+    readonly usesColor: boolean;
+}>): string;
+export declare function formatFinalSummary(input: Extract<ProgressFeedback, {
+    readonly kind: "final";
+}>): string;

package/types/project-run/progress-rendering/renderer-lifecycle.d.ts

@@ -0,0 +1,24 @@
+import type { ProgressClock, ProgressFeedback, ProgressRenderer, ProgressWriter } from "./renderer.ts";
+/** Maintains the mutable lifecycle state and the TTY-only running terminal region. */
+export declare class ProgressRendererController implements ProgressRenderer {
+    readonly refreshesRunningRegion: boolean;
+    private readonly clock;
+    private readonly writer;
+    private completedCount;
+    private preparedTotal;
+    private renderedRunningRows;
+    private readonly running;
+    private readonly usesColor;
+    constructor(writer: ProgressWriter, clock: ProgressClock);
+    refresh(): void;
+    render(feedback: ProgressFeedback): void;
+    private prepare;
+    private start;
+    private settle;
+    private finish;
+    private eraseRunningRegion;
+    private redrawRunningRegion;
+    private removeRunningCheck;
+    private updateRunningDurations;
+    private requirePrepared;
+}