@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/project-run/check-execution/execution-finalization.ts

@@ -1,16 +1,19 @@
 import type { CheckMessage } from "../../check/check.ts";
 import type { CoreSnapshot } from "../../check-settlement/facts.ts";
-import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import type {
+  NormalizedCheck,
+  SchedulerMeasurementContext
+} from "../../project-definition/project-definition.ts";
 import type { SettledTask } from "../task-scheduler/scheduler.ts";
 import type { CheckDuration, CheckRunMessage } from "../result.ts";
 import {
   CheckExecutionInvariantFailure,
   recordSettledCheck,
   type CheckIdentity,
+  type CheckExecutionState,
   type SettledCheckFacts
 } from "./execution-settlement.ts";
-import type { PreparedCheck } from "./preflight.ts";
-import type { CheckExecutionState, ResolvedCheckExecution } from "./resolved-checks.ts";
+import type { ResolvedCheckExecution } from "./resolved-execution-result.ts";
 
 const EMPTY_MESSAGES: readonly CheckMessage[] = Object.freeze([]);
 
@@ -18,40 +21,70 @@ const EMPTY_MESSAGES: readonly CheckMessage[] = Object.freeze([]);
 export function closeResolvedChecks(
   input: Readonly<{
     readonly allChecks: readonly NormalizedCheck[];
+    readonly effectiveCheckIds: readonly string[];
     readonly graphRun: Awaited<
-      ReturnType<typeof import("../task-scheduler/scheduler.ts").runTaskGraph<void>>
+      ReturnType<typeof import("../task-scheduler/scheduler.ts").runTaskGraph<boolean>>
     >;
-    readonly readyChecks: readonly PreparedCheck[];
     readonly state: CheckExecutionState;
   }>
 ): ResolvedCheckExecution {
   try {
     assertNoTaskEngineFailures(input.graphRun.settlements);
+    if (input.graphRun.admissionPolicyFault !== undefined) {
+      return closeAdmissionPolicyFailed({
+        normalizedChecks: input.allChecks,
+        state: input.state,
+        terminalSchedulerMeasurement: input.graphRun.terminalMeasurement
+      });
+    }
     if (input.graphRun.cancelled) {
       return closeCancelledExecution({
         normalizedChecks: input.allChecks,
-        preparedChecks: input.readyChecks,
-        state: input.state
+        state: input.state,
+        terminalSchedulerMeasurement: input.graphRun.terminalMeasurement
       });
     }
-    assertEveryCheckClosed(input.readyChecks, input.graphRun.settlements);
-    return resolvedExecution("completed", input.state.session.freeze(), input.state);
+    assertEveryCheckClosed(input.allChecks, input.graphRun.settlements);
+    return completedResolvedExecution(
+      input.effectiveCheckIds,
+      input.state.session.freeze(),
+      input.state,
+      input.graphRun.terminalMeasurement
+    );
   } catch (error) {
     throw trustedFailure(error);
   }
 }
 
+export function closeAdmissionPolicyFailed(
+  input: Readonly<{
+    readonly normalizedChecks: readonly NormalizedCheck[];
+    readonly state: CheckExecutionState;
+    readonly terminalSchedulerMeasurement?: SchedulerMeasurementContext;
+  }>
+): ResolvedCheckExecution {
+  input.state.session.closeUnresolvedAsCancelled();
+  const snapshot = input.state.session.freeze();
+  settleUnstartedCancelledChecks({ ...input, snapshot });
+  return resolvedExecution(
+    "admission-policy-failed",
+    snapshot,
+    input.state,
+    input.terminalSchedulerMeasurement
+  );
+}
+
 export function closeCancelledExecution(
   input: Readonly<{
     readonly normalizedChecks: readonly NormalizedCheck[];
-    readonly preparedChecks: readonly PreparedCheck[];
     readonly state: CheckExecutionState;
+    readonly terminalSchedulerMeasurement?: SchedulerMeasurementContext;
   }>
 ): ResolvedCheckExecution {
   input.state.session.closeUnresolvedAsCancelled();
   const snapshot = input.state.session.freeze();
   settleUnstartedCancelledChecks({ ...input, snapshot });
-  return resolvedExecution("cancelled", snapshot, input.state);
+  return resolvedExecution("cancelled", snapshot, input.state, input.terminalSchedulerMeasurement);
 }
 
 export function checkIdentity(
@@ -73,21 +106,37 @@ export function trustedFailure(error: unknown): CheckExecutionInvariantFailure {
 }
 
 function resolvedExecution(
-  kind: ResolvedCheckExecution["kind"],
+  kind: Exclude<ResolvedCheckExecution["kind"], "completed">,
   snapshot: CoreSnapshot,
-  state: CheckExecutionState
+  state: CheckExecutionState,
+  terminalSchedulerMeasurement: SchedulerMeasurementContext | undefined
 ): ResolvedCheckExecution {
   return Object.freeze({
     kind,
     ...checkRunSummaries(snapshot, state.settledFactsByCheckId),
-    snapshot
+    snapshot,
+    ...(terminalSchedulerMeasurement === undefined ? {} : { terminalSchedulerMeasurement })
+  });
+}
+
+function completedResolvedExecution(
+  effectiveCheckIds: readonly string[],
+  snapshot: CoreSnapshot,
+  state: CheckExecutionState,
+  terminalSchedulerMeasurement: SchedulerMeasurementContext | undefined
+): Extract<ResolvedCheckExecution, { readonly kind: "completed" }> {
+  return Object.freeze({
+    kind: "completed",
+    ...checkRunSummaries(snapshot, state.settledFactsByCheckId),
+    effectiveCheckIds,
+    snapshot,
+    ...(terminalSchedulerMeasurement === undefined ? {} : { terminalSchedulerMeasurement })
   });
 }
 
 function settleUnstartedCancelledChecks(
   input: Readonly<{
     readonly normalizedChecks: readonly NormalizedCheck[];
-    readonly preparedChecks: readonly PreparedCheck[];
     readonly snapshot: CoreSnapshot;
     readonly state: CheckExecutionState;
   }>
@@ -95,9 +144,6 @@ function settleUnstartedCancelledChecks(
   const normalizedByCheckId = new Map(
     input.normalizedChecks.map((check) => [check.definition.checkId, check])
   );
-  const preparedByCheckId = new Map(
-    input.preparedChecks.map((check) => [check.definition.checkId, check])
-  );
   for (const check of input.snapshot.checks) {
     if (input.state.settledFactsByCheckId.has(check.checkId)) continue;
     const normalized = normalizedByCheckId.get(check.checkId);
@@ -109,7 +155,7 @@ function settleUnstartedCancelledChecks(
     recordSettledCheck({
       check: checkIdentity(normalized),
       durationMs: null,
-      messages: preparedByCheckId.get(check.checkId)?.preflightMessages ?? EMPTY_MESSAGES,
+      messages: EMPTY_MESSAGES,
       outcome: check.outcome,
       phase: "execution",
       state: input.state
@@ -135,7 +181,10 @@ function checkRunSummaries(
       throw new CheckExecutionInvariantFailure("Check settled facts are missing a Check");
     }
     checkDurations.push(
-      Object.freeze({ checkId: check.checkId, durationMs: settledFacts.durationMs })
+      Object.freeze({
+        checkId: check.checkId,
+        durationMs: settledFacts.durationMs
+      })
     );
     messages.push(
       ...settledFacts.messages.map((message) =>
@@ -149,22 +198,47 @@ function checkRunSummaries(
   });
 }
 
-function assertNoTaskEngineFailures(settlements: readonly SettledTask<void>[]): void {
+/** Closes one Scheduler-blocked Check before a terminal observer may start. */
+export function settleBlockedDependent(
+  input: Readonly<{
+    readonly check: NormalizedCheck;
+    readonly dependencyIds: readonly string[];
+    readonly state: CheckExecutionState;
+  }>
+): void {
+  const scope = input.state.session.openCheckScope(input.check.definition.checkId);
+  const outcome = scope.settleProduct(
+    Object.freeze({
+      status: "unavailable" as const,
+      reason: Object.freeze({
+        code: "dependency-not-passed",
+        checkIds: Object.freeze([...input.dependencyIds])
+      })
+    })
+  );
+  recordSettledCheck({
+    check: checkIdentity(input.check),
+    durationMs: null,
+    messages: EMPTY_MESSAGES,
+    outcome,
+    phase: "dependency",
+    state: input.state
+  });
+}
+
+function assertNoTaskEngineFailures(settlements: readonly SettledTask<boolean>[]): void {
   for (const settled of settlements) {
     if (settled.settlement.kind === "failed") {
       throw new CheckExecutionInvariantFailure(
         "Task engine received an unexpected execution failure"
       );
     }
-    if (settled.settlement.kind === "blocked") {
-      throw new CheckExecutionInvariantFailure("Task engine blocked a Product Check");
-    }
   }
 }
 
 function assertEveryCheckClosed(
   checks: readonly NormalizedCheck[],
-  settlements: readonly SettledTask<void>[]
+  settlements: readonly SettledTask<boolean>[]
 ): void {
   if (settlements.some((settled) => settled.settlement.kind === "cancelled-before-start")) {
     throw new CheckExecutionInvariantFailure("Non-cancelled Task graph left a Check unstarted");

package/src/project-run/check-execution/execution-settlement.ts

@@ -6,7 +6,8 @@ import {
   type DiagnosticLogger
 } from "../diagnostic-logging/logger.ts";
 import { parseCheckTerminalResult } from "./terminal-result.ts";
-import type { CheckExecutionLifecycle } from "./resolved-checks.ts";
+import { combineCheckMessages } from "./messages.ts";
+import type { CheckExecutionLifecycle } from "./lifecycle.ts";
 import type { executeCheckCallback } from "./callback.ts";
 
 export type CheckIdentity = Readonly<{
@@ -21,11 +22,15 @@ export interface SettledCheckFacts {
 }
 
 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 class CheckExecutionInvariantFailure extends Error {
   public constructor(message: string) {
     super(message);
@@ -46,7 +51,10 @@ export function settleCallback(
   const { callback } = input;
   if (callback.source === "product") {
     const outcome = input.scope.settleProduct(callback.result);
-    return Object.freeze({ messages: input.preflightMessages, outcome });
+    return Object.freeze({
+      messages: combineCheckMessages(input.preflightMessages, callback.consoleMessages),
+      outcome
+    });
   }
   const terminal = parseCheckTerminalResult(callback.result);
   if (terminal === undefined) {
@@ -67,8 +75,8 @@ export function settleCallback(
   return Object.freeze({
     messages:
       terminal !== undefined && settlement.authorResultAccepted
-        ? Object.freeze([...input.preflightMessages, ...terminal.messages])
-        : input.preflightMessages,
+        ? combineCheckMessages(input.preflightMessages, callback.consoleMessages, terminal.messages)
+        : combineCheckMessages(input.preflightMessages, callback.consoleMessages),
     outcome: settlement.outcome
   });
 }
@@ -80,7 +88,7 @@ export function recordSettledCheck(
     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 {
@@ -101,7 +109,8 @@ export function recordSettledCheck(
     ),
     details: {
       durationMs: input.durationMs,
-      ...(input.messages.length === 0 ? {} : { messages: input.messages }),
+      messageCount: input.messages.length,
+      phase: input.phase,
       ...diagnosticSettledOutcome(input.outcome)
     }
   });
@@ -112,6 +121,7 @@ export function recordSettledCheck(
       outcome: input.outcome,
       durationMs: input.durationMs,
       messages: input.messages,
+      records: input.state.session.readSettledCheckRecords(input.check.checkId),
       visibility: input.check.visibility
     })
   );
@@ -121,13 +131,11 @@ function diagnosticSettledOutcome(outcome: CheckOutcome): Readonly<Record<string
   switch (outcome.status) {
     case "passed":
     case "failed":
-      return Object.freeze({ data: summarizeDiagnosticValue(outcome.data) });
+      return Object.freeze({ status: outcome.status });
     case "not-applicable":
-      return outcome.reason === undefined
-        ? Object.freeze({})
-        : Object.freeze({ reason: outcome.reason });
+      return Object.freeze({ reasonCode: outcome.reason?.code ?? null, status: outcome.status });
     case "unavailable":
-      return Object.freeze({ reason: outcome.reason });
+      return Object.freeze({ reasonCode: outcome.reason.code, status: outcome.status });
   }
 }
 

package/src/project-run/check-execution/flag-controls.ts

@@ -0,0 +1,132 @@
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { diagnosticTags, type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+
+export 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 function selectEffectiveCheckIds(
+  checks: readonly NormalizedCheck[],
+  flags: readonly string[]
+): readonly string[] {
+  const expandedCheckIds = new Set<string>();
+  const selectedCheckIds = new Set<string>();
+  const checksByCheckId = new Map(
+    checks.map((check) => [check.definition.checkId, check] as const)
+  );
+
+  for (const check of checks) {
+    const enablement = check.enabledByFlags;
+    if (enablement !== undefined && !matchesFlagEnablement(enablement, flags)) continue;
+
+    if (enablement?.propagateDependsOn === true) {
+      selectCheckAndDependsOnClosure(check, checksByCheckId, expandedCheckIds, selectedCheckIds);
+      continue;
+    }
+    selectedCheckIds.add(check.definition.checkId);
+  }
+
+  return Object.freeze([...selectedCheckIds].sort());
+}
+
+/** Resolves all flag-controlled outcomes before Scheduler admission or Check-owned work. */
+export function resolveFlagControlSettlements(
+  input: Readonly<{
+    readonly checks: readonly NormalizedCheck[];
+    readonly diagnosticLogger?: DiagnosticLogger;
+    readonly effectiveCheckIds: readonly string[];
+    readonly signal: AbortSignal | undefined;
+  }>
+): readonly FlagControlSettlement[] {
+  if (input.signal?.aborted === true) return Object.freeze([]);
+
+  const settlements: FlagControlSettlement[] = [];
+  const selectedCheckIds = new Set(input.effectiveCheckIds);
+  for (const check of input.checks) {
+    const settlement = resolveFlagControl(check, selectedCheckIds);
+    if (settlement === undefined) continue;
+    settlements.push(settlement);
+    input.diagnosticLogger?.observe({
+      event: "control.resolved",
+      tags: diagnosticTags(
+        `CHECK:${check.definition.checkId}`,
+        "CONTROL",
+        FLAG_CONDITION_NOT_MATCHED_CODE.toUpperCase()
+      ),
+      details: {
+        enabledByFlags: check.enabledByFlags,
+        outcome: settlement.outcome
+      }
+    });
+  }
+  return Object.freeze(settlements);
+}
+
+function resolveFlagControl(
+  check: NormalizedCheck,
+  selectedCheckIds: ReadonlySet<string>
+): FlagControlSettlement | undefined {
+  if (check.enabledByFlags === undefined || selectedCheckIds.has(check.definition.checkId)) {
+    return undefined;
+  }
+  return Object.freeze({
+    check: Object.freeze({
+      definition: check.definition,
+      visibility: check.visibility
+    }),
+    outcome: Object.freeze({
+      status: "not-applicable",
+      reason: Object.freeze({ code: FLAG_CONDITION_NOT_MATCHED_CODE })
+    })
+  });
+}
+
+function selectCheckAndDependsOnClosure(
+  check: NormalizedCheck,
+  checksByCheckId: ReadonlyMap<string, NormalizedCheck>,
+  expandedCheckIds: Set<string>,
+  selectedCheckIds: Set<string>
+): void {
+  const checkId = check.definition.checkId;
+  if (expandedCheckIds.has(checkId)) return;
+  expandedCheckIds.add(checkId);
+  selectedCheckIds.add(checkId);
+
+  for (const dependencyId of check.dependsOn) {
+    const dependency = checksByCheckId.get(dependencyId);
+    if (dependency === undefined) {
+      throw new Error("Validated Check graph has an unavailable dependency");
+    }
+    selectCheckAndDependsOnClosure(dependency, checksByCheckId, expandedCheckIds, selectedCheckIds);
+  }
+}
+
+function matchesFlagEnablement(
+  enablement: NonNullable<NormalizedCheck["enabledByFlags"]>,
+  runFlags: readonly string[]
+): boolean {
+  const isPresentInRun = (flag: string): boolean => runFlags.includes(flag);
+  switch (enablement.mode) {
+    case "all":
+      return enablement.flags.every(isPresentInRun);
+    case "any":
+      return enablement.flags.some(isPresentInRun);
+    case "none":
+      return !enablement.flags.some(isPresentInRun);
+    case "not-all":
+      return !enablement.flags.every(isPresentInRun);
+  }
+}

package/src/project-run/check-execution/lifecycle.ts

@@ -0,0 +1,21 @@
+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/src/project-run/check-execution/messages.ts

@@ -7,6 +7,14 @@ import {
 
 const EMPTY_MESSAGES: readonly CheckMessage[] = Object.freeze([]);
 
+/** Preserves phase-local order while avoiding mutable or per-call empty message collections. */
+export function combineCheckMessages(
+  ...collections: readonly (readonly CheckMessage[])[]
+): readonly CheckMessage[] {
+  const messages = collections.flat();
+  return messages.length === 0 ? EMPTY_MESSAGES : Object.freeze(messages);
+}
+
 /** Parses the shared closed Check-message attachment without retaining author input. */
 export function parseCheckMessages(value: unknown): readonly CheckMessage[] | undefined {
   if (value === undefined) return EMPTY_MESSAGES;

package/src/project-run/check-execution/plan.ts

@@ -1,5 +1,9 @@
 import type { TaskGraph, TaskNode, TaskScope } from "../task-scheduler/graph.ts";
 import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import {
+  EMPTY_RESOURCE_UNIT_MAPPING,
+  type ResourceUnitMapping
+} from "../../project-definition/resource-unit-mapping.ts";
 
 /**
  * Pure executable-Check projection. Check ids are the only scheduler Task
@@ -8,25 +12,25 @@ import type { NormalizedCheck } from "../../project-definition/project-definitio
  */
 export function planStaticCheckGraph(
   checks: readonly NormalizedCheck[],
-  options: Readonly<{ readonly alreadySettledCheckIds?: ReadonlySet<string> }> = {}
+  resourceCapacities: ResourceUnitMapping = EMPTY_RESOURCE_UNIT_MAPPING
 ): TaskGraph {
-  const alreadySettledCheckIds = options.alreadySettledCheckIds ?? new Set<string>();
-  const tasks = checks.map((check) => taskForCheck(check, alreadySettledCheckIds));
+  const tasks = checks.map(taskForCheck);
   const scopes = checks.map(scopeForCheck);
   return Object.freeze({
+    resourceCapacities,
     tasks: Object.freeze(tasks),
     scopes: Object.freeze(scopes)
   });
 }
 
-function taskForCheck(
-  check: NormalizedCheck,
-  alreadySettledCheckIds: ReadonlySet<string>
-): TaskNode {
+function taskForCheck(check: NormalizedCheck): TaskNode {
   return Object.freeze({
-    dependsOn: check.dependsOn.filter((checkId) => !alreadySettledCheckIds.has(checkId)),
+    admissionPriority: check.admissionPriority,
+    dependsOn: check.dependsOn,
     id: check.definition.checkId,
     mutex: check.mutex,
+    observes: check.observes,
+    resourceClaims: check.resourceClaims,
     scopeId: scopeIdFor(check)
   });
 }