@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -0,0 +1,5 @@
+import type { CheckAggregation } from "../controls/contract.ts";
+import { type NonConfigurationRunResult } from "../result.ts";
+import type { Invocation } from "./run.ts";
+/** Executes the post-validation invocation phases, from change preparation through Scheduler completion. */
+export declare function executePlannedInvocation(invocation: Invocation, aggregation: CheckAggregation | undefined): Promise<NonConfigurationRunResult>;

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 { OutputStatuses } from "../outputs/status.ts";
+import { type RunResult } from "../result.ts";
+import { type DiagnosticLoggerFactory, type DiagnosticLoggingRouter } from "../diagnostic-logging/logger.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 effects 与 prepared custom strategy 的 optional `terminalEffect` 所形成的 terminal participant
+     * 状态；它不能由 RunControls 注入或覆盖。
+     */
+    readonly terminalEffects: RunOutputStatus;
+}
+export interface OutputStatuses {
+    /** Enables a runtime-only terminal participant after successful preparation. */
+    readonly enableTerminalEffects: () => 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>>, initialTerminalEffectsEnabled: boolean): OutputStatuses;
+export declare function failedOutput(statuses: RunOutputStatuses): keyof RunOutputStatuses | undefined;

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

@@ -1,11 +1,14 @@
-import type { CheckExecutionLifecycle } from "../check-execution/resolved-checks.ts";
+import type { CheckExecutionLifecycle, InvocationLifecycle } from "../check-execution/lifecycle.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";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.ts";
+import type { OutputStatuses } from "../outputs/status.ts";
 export interface ProgressRendering {
+    /** Closes only an already-created file tee; it never creates a writer after pre-work termination. */
+    readonly close: () => void;
     readonly final: (input: ProgressFinalFeedback) => void;
-    readonly lifecycle: CheckExecutionLifecycle;
-    readonly prepared: (totalChecks: number) => void;
+    readonly checkLifecycle: CheckExecutionLifecycle;
+    readonly invocationLifecycle: InvocationLifecycle;
+    readonly prepared: (totalChecks: number, quietPassOmissionConfiguredCount: number) => void;
 }
 export interface ProgressFinalFeedback {
     readonly counts: ProgressOutcomeCounts;
@@ -21,8 +24,10 @@ export interface ProgressRefreshScheduler {
 }
 export interface ProgressRenderingDependencies {
     readonly clock?: ProgressClock;
+    /** Caller-owned exact progress transcript target for this invocation; `null` keeps terminal-only output. */
+    readonly file?: string | null;
     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;
+/** Owns terminal progress and its optional file tee; terminal output survives a file-only failure. */
+export declare function createProgressRendering(configuration: ResolvedProgressRenderingOutput, statuses: OutputStatuses, dependencies?: ProgressRenderingDependencies): ProgressRendering;

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

@@ -1,7 +1,9 @@
 import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { CoreRecord } from "../../check-settlement/facts.ts";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.ts";
 import type { ProgressFeedback } from "./renderer.ts";
 export declare function formatRunningRow(input: Readonly<{
-    readonly displayIndex: number;
+    readonly displayIndex: number | undefined;
     readonly displayName: string;
     readonly elapsedMs: number | null;
     readonly totalChecks: number;
@@ -9,15 +11,24 @@ export declare function formatRunningRow(input: Readonly<{
 export declare function shouldPresentSettledFeedback(feedback: Extract<ProgressFeedback, {
     readonly kind: "settled";
 }>): boolean;
+export declare function isFlagConditionNotMatchedFeedback(feedback: Extract<ProgressFeedback, {
+    readonly kind: "settled";
+}>): boolean;
+export declare function formatFlagConditionNotMatchedBlock(displayNames: readonly [string, ...string[]]): string;
 export declare function formatSettledBlock(input: Readonly<{
-    readonly completionOrdinal: number;
+    readonly completionOrdinal: number | undefined;
     readonly displayName: string;
     readonly durationMs: number | null;
     readonly messages: readonly CheckMessage[];
     readonly outcome: CheckOutcome;
+    readonly records: readonly CoreRecord[];
     readonly totalChecks: number;
     readonly usesColor: boolean;
+    readonly progressRendering: ResolvedProgressRenderingOutput;
 }>): string;
 export declare function formatFinalSummary(input: Extract<ProgressFeedback, {
     readonly kind: "final";
+}> & Readonly<{
+    readonly quietPassOmissionConfiguredCount: number;
+    readonly quietPassOmittedCount: number;
 }>): string;

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

@@ -1,21 +1,28 @@
 import type { ProgressClock, ProgressFeedback, ProgressRenderer, ProgressWriter } from "./renderer.ts";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.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 readonly flagConditionNotMatchedDisplayNames;
+    private quietPassOmissionConfiguredCount;
+    private quietPassOmittedCount;
     private preparedTotal;
     private renderedRunningRows;
     private readonly running;
     private readonly usesColor;
-    constructor(writer: ProgressWriter, clock: ProgressClock);
+    private readonly progressRendering;
+    constructor(writer: ProgressWriter, clock: ProgressClock, progressRendering: ResolvedProgressRenderingOutput);
     refresh(): void;
     render(feedback: ProgressFeedback): void;
     private prepare;
     private start;
     private settle;
     private finish;
+    private completeFlagControl;
+    private flushFlagConditionNotMatchedChecks;
     private eraseRunningRegion;
     private redrawRunningRegion;
     private removeRunningCheck;

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

@@ -1,25 +1,33 @@
-import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.ts";
+import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { CoreRecord } from "../../check-settlement/facts.ts";
+import type { ResolvedProgressRenderingOutput } from "../../project-definition/project-definition.ts";
 export interface ProgressWriter {
     readonly color: boolean;
     readonly isTTY: boolean;
     readonly term: string | undefined;
+    close?(): void;
     write(content: string): void;
 }
 export type ProgressFeedback = Readonly<{
     readonly kind: "prepared";
+    readonly quietPassOmissionConfiguredCount: number;
     readonly totalChecks: number;
+} | {
+    readonly kind: "flag-control-completed";
 } | {
     readonly kind: "started";
     readonly checkId: string;
     readonly displayName: string;
+    readonly omitQuietPassedRow: boolean;
 } | {
     readonly kind: "settled";
     readonly checkId: string;
     readonly displayName: string;
     readonly outcome: CheckOutcome;
     readonly durationMs: number | null;
-    readonly visibility: CheckVisibility;
+    readonly omitQuietPassedRow: boolean;
     readonly messages: readonly CheckMessage[];
+    readonly records: readonly CoreRecord[];
 } | {
     readonly kind: "final";
     readonly execution: "cancelled" | "completed";
@@ -41,4 +49,4 @@ export interface ProgressClock {
     now(): number;
 }
 /** Product-private lifecycle presentation with one owner for feedback and its writer. */
-export declare function createProgressRenderer(writer: ProgressWriter, clock?: ProgressClock): ProgressRenderer;
+export declare function createProgressRenderer(writer: ProgressWriter, clock?: ProgressClock, progressRendering?: ResolvedProgressRenderingOutput): ProgressRenderer;

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

@@ -1,7 +1,8 @@
-import type { CheckProjectContext } from "../check/check.ts";
-import type { RunControls } from "./controls/contract.ts";
+import type { CheckProjectContext, ProjectChanges } from "../check/check.ts";
+import type { ResolvedInvocationPaths } from "./invocation/paths.ts";
 /** Materializes only invocation-wide callback input; Check-local options own domain configuration. */
 export declare function createProjectContext(input: Readonly<{
-    readonly controls: RunControls;
-    readonly root: string;
+    readonly changes?: ProjectChanges;
+    readonly flags: readonly string[];
+    readonly paths: ResolvedInvocationPaths;
 }>): CheckProjectContext;

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

@@ -3,69 +3,103 @@ import type { RunControlDiagnostic } from "./controls/validation-result.ts";
 import type { CheckAggregate, RunControls } from "./controls/contract.ts";
 import type { CheckMessageLevel } from "../check/check.ts";
 import type { CoreSnapshot } from "../check-settlement/facts.ts";
-import type { RunOutputStatuses } from "./output-status.ts";
+import type { RunOutputStatuses } from "./outputs/status.ts";
+/** Product 不能形成正常 Run 结果时的稳定 invocation diagnostic。 */
 export type RunDiagnostic = Readonly<{
-    readonly code: "task-graph-invalid" | "task-engine-failed" | "publication-model-failed";
+    /** 失败的 Run-owned execution 或 planning boundary；它不是任何 Check 的 terminal status。 */
+    readonly code: "admission-policy-failed" | "admission-strategy-preparation-failed" | "task-graph-invalid" | "task-engine-failed" | "publication-model-failed";
 }>;
+/** 一项 executable Check 的最终 duration readback。 */
 export type CheckDuration = Readonly<{
+    /** 与 snapshot 中 Check facts 相同的 stable Check identity。 */
     readonly checkId: string;
+    /** 已测量的 execution duration；未进入 execution 的 Check 为 `null`，不是零时长。 */
     readonly durationMs: number | null;
 }>;
+/** Run 在 Check terminal lifecycle 中接受的人读 message。 */
 export interface CheckRunMessage {
+    /** 产生 message 的 stable Check identity。 */
     readonly checkId: string;
+    /** author message 或已捕获 console output 的 presentation severity。 */
     readonly level: CheckMessageLevel;
+    /** owning Check 或 Product capture 使用的稳定 message code。 */
     readonly code: string;
+    /** 人读正文；不能代替 snapshot 中的 terminal outcome。 */
     readonly message: string;
 }
+/** 只有已形成 terminal Check facts 的 Run branch 才具备的完整结果 readback。 */
 export interface RunResultFacts {
-    readonly aggregate: CheckAggregate | null;
+    /** 有完整 terminal Check facts 时，由有效 Check 列表形成的 invocation-level conclusion。 */
+    readonly aggregate: CheckAggregate;
+    /** 按 canonical Check order 的 duration facts；未执行 Check 仍以 `null` 保留。 */
     readonly checkDurations: readonly CheckDuration[];
+    /** 已接受的 author 与 console-capture messages，不决定 Check outcome。 */
     readonly checkMessages: readonly CheckRunMessage[];
+    /** 已结算的完整 Check 与 supplemental Record facts。 */
     readonly snapshot: CoreSnapshot;
 }
 /** 一次 Project Run 的可判别结果；output failure 保留已结算 facts。 */
 export type RunResult = Readonly<{
+    /** Definition、RunControls 或 aggregation selection 无效；没有执行任何 Check author callback。 */
     readonly kind: "configuration";
+    /** Definition normalization 时仍可报告、但不单独阻止本 branch 的 warning。 */
     readonly definitionWarnings: readonly DefinitionWarning[];
+    /** 指向被拒绝 Definition 或 RunControls value 的 closed diagnostic。 */
     readonly diagnostic: ProjectDefinitionDiagnostic | RunControlDiagnostic;
 } | {
+    /** 配置有效，但 static Check graph 不能进入 execution planning。 */
     readonly kind: "planning";
+    /** normalized declarative Definition 的 matching signal；不包含 RunControls 或 outcome。 */
     readonly declarativeFingerprint: string;
     readonly definitionWarnings: readonly DefinitionWarning[];
+    /** 这次 planning 失败的 Product diagnostic。 */
     readonly diagnostic: RunDiagnostic;
+    /** 配置有效后各 terminal output participant 的独立状态。 */
     readonly outputs: RunOutputStatuses;
 } | {
+    /** invocation 在 Check work 开始前或 planning 中响应 caller cancellation。 */
     readonly kind: "cancelled";
     readonly declarativeFingerprint: string;
     readonly definitionWarnings: readonly DefinitionWarning[];
     readonly outputs: RunOutputStatuses;
+    /** 取消发生在尚未形成 terminal Check facts 的阶段。 */
     readonly phase: "pre-work" | "planning";
 } | {
+    /** invocation 在至少可能已开始 Check work 的 execution 阶段响应 caller cancellation。 */
     readonly kind: "cancelled";
     readonly declarativeFingerprint: string;
     readonly definitionWarnings: readonly DefinitionWarning[];
     readonly outputs: RunOutputStatuses;
+    /** 此 branch 总在 terminal Check facts 形成后的 execution cancellation 返回。 */
     readonly phase: "execution";
+    /** 按 canonical Check order 的 duration facts；未执行 Check 为 `null`。 */
     readonly checkDurations: readonly CheckDuration[];
+    /** cancellation 前已接受的 author 与 console-capture messages。 */
     readonly checkMessages: readonly CheckRunMessage[];
+    /** cancellation 时已结算的完整 Check 与 supplemental Record facts。 */
     readonly snapshot: CoreSnapshot;
 } | ({
+    /** 所有 Check 已完成 terminal settlement；不表示每项 Check 都 `passed`。 */
     readonly kind: "completed";
     readonly declarativeFingerprint: string;
     readonly definitionWarnings: readonly DefinitionWarning[];
     readonly outputs: RunOutputStatuses;
 } & RunResultFacts) | {
+    /** Product execution/settlement infrastructure 失败；不把它误表示为 Check `failed`。 */
     readonly kind: "execution";
     readonly declarativeFingerprint: string;
     readonly definitionWarnings: readonly DefinitionWarning[];
+    /** 停止正常 execution 的 Product diagnostic；本 branch 不提供 partial snapshot。 */
     readonly diagnostic: RunDiagnostic;
     readonly outputs: RunOutputStatuses;
 } | ({
+    /** Check facts 已完整结算，但至少一个 terminal output participant 失败。 */
     readonly kind: "output";
     readonly declarativeFingerprint: string;
     readonly definitionWarnings: readonly DefinitionWarning[];
+    /** 失败的 machine、progress、diagnostic 或 scheduler-measurement output 类别。 */
     readonly diagnostic: Readonly<{
-        readonly code: "machine-publication-failed" | "progress-rendering-failed" | "diagnostic-logging-failed";
+        readonly code: "machine-publication-failed" | "progress-rendering-failed" | "diagnostic-logging-failed" | "scheduler-terminal-effects-failed";
     }>;
     readonly outputs: RunOutputStatuses;
 } & RunResultFacts)>;

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

@@ -1,18 +1,19 @@
 import type { ProjectDefinition } from "../project-definition/project-definition.ts";
 import type { RunControls } from "./controls/contract.ts";
 import type { RunResult } from "./result.ts";
-export type { RunOutputStatus, RunOutputStatuses } from "./output-status.ts";
+export type { RunOutputStatus, RunOutputStatuses } from "./outputs/status.ts";
 export type { RunDiagnostic, RunResult } from "./result.ts";
 /**
- * 在调用方的 Bun runtime 中执行一个由项目拥有的 Project Definition。
+ * 在调用方的 Node runtime 中执行一个由项目拥有的 Project Definition。
  *
  * @param definition - Project Definition input；{@link defineConfig} 补齐 defaults，run 在 invocation 前验证。
  * @param controls - 本次 invocation context 与 outputs 使用的闭合控制值。
  * @returns ordinary configuration、planning、execution、cancellation 与 output failures 通过 `RunResult`
  * 返回；调用方先按 `kind` narrow。
- * @remarks Definition validation 关闭 authoring grammar；可选 Check preflight 组成 invocation execution barrier，
- * 并在 execution callback、dependency resolver 或 scanner 前完成。`output` branch 同时提供完整 final
- * snapshot 与 output failure diagnostic。
+ * @remarks Definition validation 关闭 authoring grammar；可选 Check preparation 在其 Task 通过直接 relation
+ * readiness 后被 Scheduler admission 时运行，并先于该 Check 自己的 execution callback。它受该 Task 的
+ * mutex、capacity、priority 与 cancellation 约束，而不是 invocation-wide barrier。`output` branch 同时提供
+ * 完整 final snapshot 与 output failure diagnostic。
  */
 export declare function run(definition: ProjectDefinition, controls?: RunControls): Promise<RunResult>;
 export declare function run(definition: unknown, controls?: unknown): Promise<RunResult>;

package/types/project-run/task-scheduler/admission-core/compiled-graph-lookup.d.ts

@@ -0,0 +1,10 @@
+/** Required accessors for compiler-owned dense slot indexes. */
+import type { PlannedTask } from "../graph.ts";
+import type { CompiledAdmissionGraph } from "./compiled-graph.ts";
+export declare function requiredTaskForCompiled(compiled: CompiledAdmissionGraph, taskSlot: number): PlannedTask;
+export declare function requiredTaskMutexSlotsForCompiled(compiled: CompiledAdmissionGraph, taskSlot: number): CompiledAdmissionGraph["taskMutexSlots"][number];
+export declare function requiredTaskResourceClaimsForCompiled(compiled: CompiledAdmissionGraph, taskSlot: number): CompiledAdmissionGraph["taskResourceClaims"][number];
+export declare function requiredReverseDependenciesForCompiled(compiled: CompiledAdmissionGraph, taskSlot: number): CompiledAdmissionGraph["relationIndexes"]["reverseDependencies"][number];
+export declare function requiredReverseObservationsForCompiled(compiled: CompiledAdmissionGraph, taskSlot: number): CompiledAdmissionGraph["relationIndexes"]["reverseObservations"][number];
+export declare function requiredReverseMutexOccurrencesForCompiled(compiled: CompiledAdmissionGraph, mutexSlot: number): CompiledAdmissionGraph["relationIndexes"]["reverseMutexOccurrences"][number];
+export declare function requiredScopeTerminalSlotsForCompiled(compiled: CompiledAdmissionGraph, taskSlot: number): CompiledAdmissionGraph["scopeSlotsByTerminalTaskSlot"][number];

package/types/project-run/task-scheduler/admission-core/compiled-graph.d.ts

@@ -0,0 +1,31 @@
+import type { PlannedTask, PlannedTaskGraph } from "../graph.ts";
+interface RelationStaticIndexes {
+    readonly reverseDependencies: readonly (readonly number[])[];
+    readonly reverseMutexOccurrences: readonly (readonly number[])[];
+    readonly reverseObservations: readonly (readonly number[])[];
+}
+export interface CompiledAdmissionGraph {
+    readonly graph: PlannedTaskGraph;
+    readonly maxParallel: number;
+    readonly mutexSlotById: ReadonlyMap<string, number>;
+    readonly resourceCapacityBySlot: readonly number[];
+    readonly resourceSlotById: ReadonlyMap<string, number>;
+    readonly scopesById: ReadonlyMap<string, PlannedTaskGraph["scopes"][number]>;
+    readonly scopeSlotById: ReadonlyMap<string, number>;
+    readonly scopeSlotsByTerminalTaskSlot: readonly (readonly number[])[];
+    readonly taskById: ReadonlyMap<string, PlannedTask>;
+    readonly taskMutexSlots: readonly (readonly number[])[];
+    readonly taskResourceClaims: readonly (readonly Readonly<{
+        readonly resourceSlot: number;
+        readonly units: number;
+    }>[])[];
+    readonly taskActivatesScope: readonly boolean[];
+    readonly taskScopeSlots: readonly (number | undefined)[];
+    readonly taskSlotsById: ReadonlyMap<string, number>;
+    readonly taskIdsInPublicOrder: readonly string[];
+    readonly taskSlotsInPublicOrder: readonly number[];
+    readonly relationIndexes: RelationStaticIndexes;
+}
+/** Compiles a Scheduler-owned normalized graph once for an actual scheduler invocation. */
+export declare function compilePreparedAdmissionGraph(graph: PlannedTaskGraph, maxParallel: number): CompiledAdmissionGraph;
+export {};

package/types/project-run/task-scheduler/admission-core/core.d.ts

@@ -0,0 +1,57 @@
+import type { AdmissionGraph, AdmissionGraphInput, AdmissionRejectionReason, AdmissionSelectionValidation, AdmissionSelectionValidationRejectionReason, AdmissionState } from "../../../project-definition/scheduler-policy.ts";
+import { schedulerInspectionForCore } from "./projection.ts";
+import { createAdmissionCoreFromSchedulerSnapshot, createInitialAdmissionCoreState, type AdmissionCoreState } from "./selection.ts";
+import { admissionCandidatesForCore, scopeToActivateForCore, type AdmissionCoreSelection } from "./selection-query.ts";
+import type { SchedulerSettlementKind } from "../scheduler-decision-model.ts";
+export { compilePreparedAdmissionGraph } from "./compiled-graph.ts";
+export type { CompiledAdmissionGraph } from "./compiled-graph.ts";
+export { admissionCandidatesForCore, createAdmissionCoreFromSchedulerSnapshot, createInitialAdmissionCoreState, schedulerInspectionForCore, scopeToActivateForCore };
+export type { AdmissionCoreSelection, AdmissionCoreState };
+export type AdmissionCoreEffect = Readonly<{
+    readonly kind: "admitted";
+    readonly taskId: string;
+}> | Readonly<{
+    readonly dependencyIds?: readonly string[];
+    readonly kind: "settled";
+    readonly settlementKind: SchedulerSettlementKind;
+    readonly taskId: string;
+}>;
+export interface AdmissionCoreTransition {
+    /** The immutable post-state for each corresponding canonical effect. */
+    readonly effectStates: readonly AdmissionCoreState[];
+    readonly effects: readonly AdmissionCoreEffect[];
+    readonly state: AdmissionCoreState;
+}
+/** 在 exact boundary validation 和一次 static compile 后创建 standalone public factory。 */
+export declare function createAdmissionGraph(input: AdmissionGraphInput): AdmissionGraph;
+/** The canonical select action used by both the public opaque handle and the real shell. */
+export declare function selectAdmissionCore(state: AdmissionCoreState, taskId: string): Readonly<{
+    readonly accepted: true;
+    readonly transition: AdmissionCoreTransition;
+} | {
+    readonly accepted: false;
+    readonly reason: AdmissionSelectionValidationRejectionReason;
+}>;
+/** The public binary settlement action. Runtime outcome validation intentionally precedes ID checks. */
+export declare function settleAdmissionCore(state: AdmissionCoreState, taskId: string, outcome: unknown): Readonly<{
+    readonly accepted: true;
+    readonly transition: AdmissionCoreTransition;
+} | {
+    readonly accepted: false;
+    readonly reason: AdmissionRejectionReason;
+}>;
+/** Applies a real running Task settlement through the same reducer, retaining private exact kinds. */
+export declare function settleRunningAdmissionCore(state: AdmissionCoreState, taskId: string, settlementKind: Extract<SchedulerSettlementKind, "completed" | "prerequisite-unsatisfied" | "failed">): Readonly<{
+    readonly accepted: true;
+    readonly transition: AdmissionCoreTransition;
+} | {
+    readonly accepted: false;
+    readonly reason: AdmissionRejectionReason;
+}>;
+/** Private cancellation stays in the reducer/effect owner but has no public AdmissionState action. */
+export declare function cancelPendingAdmissionCore(state: AdmissionCoreState): AdmissionCoreTransition;
+/** Reconciles forced dependency blocks before the real shell publishes its next decision boundary. */
+export declare function reconcileAdmissionCore(state: AdmissionCoreState): AdmissionCoreTransition;
+export declare function validateAdmissionCoreSelection(state: AdmissionCoreState, taskId: string): AdmissionSelectionValidation;
+/** Constructs the frozen opaque public wrapper. Projection work remains lazy until its getter is read. */
+export declare function admissionStateForCore(core: AdmissionCoreState): AdmissionState;

package/types/project-run/task-scheduler/admission-core/input.d.ts

@@ -0,0 +1,4 @@
+import type { AdmissionGraphInput } from "../../../project-definition/scheduler-policy.ts";
+import { type CompiledAdmissionGraph } from "./compiled-graph.ts";
+/** Validates the exact standalone boundary before compiling the Scheduler-owned graph. */
+export declare function compileAdmissionGraphInput(input: AdmissionGraphInput): CompiledAdmissionGraph;

package/types/project-run/task-scheduler/admission-core/projection.d.ts

@@ -0,0 +1,22 @@
+import type { AdmissionCatalog, AdmissionInspection } from "../../../project-definition/scheduler-policy.ts";
+import type { PlannedTask, PlannedTaskGraph } from "../graph.ts";
+import type { AdmissionCoreState } from "./selection.ts";
+import type { SchedulerSettlementKind } from "../scheduler-decision-model.ts";
+/** Materializes the public catalog only when the public getter reads it. */
+export declare function catalogForCore(state: AdmissionCoreState): AdmissionCatalog;
+export declare function inspectionForCore(state: AdmissionCoreState): AdmissionInspection;
+/** Scheduler-only projection retained for policy choice and diagnostics, not a second transition model. */
+export declare function schedulerInspectionForCore(state: AdmissionCoreState): Readonly<{
+    readonly activeScopeIds: readonly string[];
+    readonly effectiveMaxParallel: number;
+    readonly graph: PlannedTaskGraph;
+    readonly maxParallel: number;
+    readonly pendingTasks: readonly PlannedTask[];
+    readonly runningMutexes: readonly string[];
+    readonly resources: AdmissionInspection["resources"];
+    readonly runningTaskIds: readonly string[];
+    readonly settledTasks: readonly Readonly<{
+        readonly kind: SchedulerSettlementKind;
+        readonly taskId: string;
+    }>[];
+}>;