@zxyycom/vibe-check 0.0.2 → 0.0.3

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

@@ -0,0 +1,62 @@
+/** Handles one admitted Check's preparation boundary and ready callback handoff. */
+
+import type { CheckProjectContext } from "../../check/check.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import type { ResolvedInvocationPaths } from "../invocation/paths.ts";
+import { checkIdentity } from "./execution-finalization.ts";
+import { recordSettledCheck, type CheckExecutionState } from "./execution-settlement.ts";
+import { prepareCheck, type CheckPreparationResolution } from "./preparation.ts";
+import { executeReadyCheck } from "./ready-check-execution.ts";
+
+export type CheckExecutionClock = Readonly<{ now(): number }>;
+
+export type AdmittedCheckExecutionInput = CheckExecutionState &
+  Readonly<{
+    readonly check: NormalizedCheck;
+    readonly clock: CheckExecutionClock;
+    readonly onAdmittedCheck: ((check: NormalizedCheck) => void) | undefined;
+    readonly invocationId: string;
+    readonly paths: ResolvedInvocationPaths | undefined;
+    readonly project: CheckProjectContext;
+    readonly signal: AbortSignal;
+  }>;
+
+export async function executeAdmittedCheck(input: AdmittedCheckExecutionInput): Promise<boolean> {
+  observeAdmittedCheck(input);
+  const preparation = await prepareCheck({
+    check: input.check,
+    diagnosticLogger: input.diagnosticLogger,
+    project: input.project,
+    signal: input.signal
+  });
+  if (preparation.kind === "blocked") {
+    settleBlockedPreparation(input, preparation);
+    return false;
+  }
+  return executeReadyCheck({ ...input, prepare: preparation });
+}
+
+function settleBlockedPreparation(
+  state: CheckExecutionState,
+  prepare: Extract<CheckPreparationResolution, { readonly kind: "blocked" }>
+): void {
+  const scope = state.session.openCheckScope(prepare.check.definition.checkId);
+  const outcome = scope.settleProduct(prepare.outcome);
+  recordSettledCheck({
+    check: checkIdentity(prepare.check),
+    durationMs: null,
+    messages: prepare.check.preparationMessages,
+    outcome,
+    phase: "preparation",
+    state
+  });
+}
+
+/** Diagnostic observation belongs to the invocation; it cannot revise admitted Task facts. */
+function observeAdmittedCheck(input: AdmittedCheckExecutionInput): void {
+  try {
+    input.onAdmittedCheck?.(input.check);
+  } catch {
+    // Learned diagnostic output is best-effort and has no execution consequence.
+  }
+}

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

@@ -10,6 +10,7 @@ import { CoreInvariantFailure, type TrustedCheckScope } from "../../check-settle
 import { diagnosticTags, type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
 import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
 import { invokeWithCapturedConsole } from "./console-capture.ts";
+import { diagnosticCallbackResult } from "./terminal-result.ts";
 
 const EMPTY_MESSAGES: readonly CheckMessage[] = Object.freeze([]);
 
@@ -61,7 +62,7 @@ export async function executeCheckCallback(input: CheckCallbackInput): Promise<C
       records: reporter.records,
       signal: input.signal
     });
-    const invocation = await invokeWithCapturedConsole(() => input.check.execution(context));
+    const invocation = await invokeWithCapturedConsole(() => input.check.execute(context));
     consoleMessages = invocation.messages;
     if (invocation.kind === "threw") throw invocation.error;
     const callbackResult = invocation.output;
@@ -69,7 +70,7 @@ export async function executeCheckCallback(input: CheckCallbackInput): Promise<C
       input.diagnosticLogger?.observe({
         event: "callback.cancelled",
         tags: diagnosticTags(...checkTags, "CANCELLED"),
-        details: { result: callbackResult }
+        details: { result: diagnosticCallbackResult(callbackResult, input.check.handoff) }
       });
     }
     result = input.signal.aborted

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

@@ -1,30 +1,57 @@
 import type {
+  CheckHandoffProvider,
   CheckDependencies,
   CheckOutcome,
+  DependencyHandoffReadResult,
   DependencyObservation,
   DependencyReadResult
 } from "../../check/check.ts";
+import {
+  getDefinedHandoffProviderIdentity,
+  type HandoffProviderIdentity
+} from "../../check/handoff-provider-identity.ts";
 import type { CoreCheckSession } from "../../check-settlement/session.ts";
+import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
 import { diagnosticTags, type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+import type { ParsedCheckTerminalHandoff } from "./terminal-result.ts";
+
+type RuntimeDependencyHandoffReadResult = DependencyHandoffReadResult<string, object>;
 
 export function createCheckDependencies(
   input: Readonly<{
     readonly checkId: string;
+    readonly directDependsOnCheckIds: readonly string[];
     readonly diagnosticLogger: DiagnosticLogger | undefined;
     readonly directRelationCheckIds: readonly string[];
+    readonly handoffsByCheckId: ReadonlyMap<string, ParsedCheckTerminalHandoff>;
     readonly session: CoreCheckSession;
   }>
 ): CheckDependencies {
-  return Object.freeze({
-    get: (dependencyId: string): DependencyReadResult => {
-      const result = readDirectRelation(input.session, input.directRelationCheckIds, dependencyId);
+  function get<Id extends string, Handoff extends object>(
+    dependency: CheckHandoffProvider<Id, Handoff>
+  ): DependencyHandoffReadResult<Id, Handoff>;
+  function get(dependency: string): DependencyReadResult;
+  function get(dependency: unknown): DependencyReadResult | RuntimeDependencyHandoffReadResult;
+  function get(dependency: unknown): DependencyReadResult | RuntimeDependencyHandoffReadResult {
+    if (dependency === null || typeof dependency !== "object") {
+      const result = readDirectRelation(input.session, input.directRelationCheckIds, dependency);
       input.diagnosticLogger?.observe({
         event: "dependency.read",
         tags: diagnosticTags(`CHECK:${input.checkId}`, "EXECUTION", "DEPENDENCY-READ"),
-        details: dependencyReadDetails(dependencyId, result)
+        details: dependencyReadDetails(dependency, result)
       });
       return result;
-    },
+    }
+    const result = readDirectDependencyHandoff(input, dependency);
+    input.diagnosticLogger?.observe({
+      event: "dependency.read",
+      tags: diagnosticTags(`CHECK:${input.checkId}`, "EXECUTION", "DEPENDENCY-READ"),
+      details: handoffDependencyReadDetails(dependency, result)
+    });
+    return result;
+  }
+  return Object.freeze({
+    get,
     list: (): readonly DependencyObservation[] => {
       const observations = listDirectRelationObservations(
         input.session,
@@ -40,6 +67,74 @@ export function createCheckDependencies(
   });
 }
 
+function readDirectDependencyHandoff(
+  input: Readonly<{
+    readonly directDependsOnCheckIds: readonly string[];
+    readonly handoffsByCheckId: ReadonlyMap<string, ParsedCheckTerminalHandoff>;
+    readonly session: CoreCheckSession;
+  }>,
+  provider: unknown
+): RuntimeDependencyHandoffReadResult {
+  const providerIdentity = handoffProviderIdentity(provider);
+  if (
+    providerIdentity === undefined ||
+    !input.directDependsOnCheckIds.includes(providerIdentity.checkId)
+  ) {
+    return handoffDependencyNotDeclared(providerIdentity?.checkId ?? handoffCheckId(provider));
+  }
+  const settledHandoff = input.handoffsByCheckId.get(providerIdentity.checkId);
+  const outcome = input.session.readSettledCheckOutcome(providerIdentity.checkId);
+  if (
+    settledHandoff === undefined ||
+    settledHandoff.identity !== providerIdentity.identity ||
+    outcome.status !== "passed"
+  ) {
+    return handoffUnavailable(providerIdentity.checkId);
+  }
+  return Object.freeze({
+    ok: true,
+    checkId: providerIdentity.checkId,
+    status: "passed",
+    data: outcome.data,
+    handoff: settledHandoff.value
+  });
+}
+
+function handoffProviderIdentity(
+  provider: unknown
+): Readonly<{ readonly checkId: string; readonly identity: HandoffProviderIdentity }> | undefined {
+  const identity = getDefinedHandoffProviderIdentity(provider);
+  const record = snapshotClosedRecord(provider);
+  if (
+    identity === undefined ||
+    record === undefined ||
+    typeof record.checkId !== "string" ||
+    record.handoff !== true
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ checkId: record.checkId, identity });
+}
+
+function handoffCheckId(provider: unknown): string {
+  const record = snapshotClosedRecord(provider);
+  return record !== undefined && typeof record.checkId === "string" ? record.checkId : "";
+}
+
+function handoffDependencyNotDeclared(checkId: string): RuntimeDependencyHandoffReadResult {
+  return Object.freeze({
+    ok: false,
+    error: Object.freeze({ code: "dependency-not-declared", checkId })
+  });
+}
+
+function handoffUnavailable(checkId: string): RuntimeDependencyHandoffReadResult {
+  return Object.freeze({
+    ok: false,
+    error: Object.freeze({ code: "upstream-handoff-unavailable", checkId })
+  });
+}
+
 function listDirectRelationObservations(
   session: CoreCheckSession,
   directRelationCheckIds: readonly string[]
@@ -75,10 +170,29 @@ function dependencyReadDetails(
   });
 }
 
+function handoffDependencyReadDetails(
+  requestedProvider: unknown,
+  result: RuntimeDependencyHandoffReadResult
+): Readonly<Record<string, unknown>> {
+  if (!result.ok) {
+    return Object.freeze({
+      error: result.error,
+      ok: false,
+      requestedCheckId: handoffCheckId(requestedProvider)
+    });
+  }
+  return Object.freeze({
+    hasData: true,
+    ok: true,
+    producer: result.checkId,
+    status: result.status
+  });
+}
+
 function readDirectRelation(
   session: CoreCheckSession,
   directRelationCheckIds: readonly string[],
-  checkId: string
+  checkId: unknown
 ): DependencyReadResult {
   if (typeof checkId !== "string" || !directRelationCheckIds.includes(checkId)) {
     return dependencyNotDeclared(checkId);

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

@@ -31,17 +31,19 @@ export function closeResolvedChecks(
   try {
     assertNoTaskEngineFailures(input.graphRun.settlements);
     if (input.graphRun.admissionPolicyFault !== undefined) {
+      const terminalSchedulerMeasurement = input.graphRun.terminalMeasurement;
       return closeAdmissionPolicyFailed({
         normalizedChecks: input.allChecks,
         state: input.state,
-        terminalSchedulerMeasurement: input.graphRun.terminalMeasurement
+        ...(terminalSchedulerMeasurement === undefined ? {} : { terminalSchedulerMeasurement })
       });
     }
     if (input.graphRun.cancelled) {
+      const terminalSchedulerMeasurement = input.graphRun.terminalMeasurement;
       return closeCancelledExecution({
         normalizedChecks: input.allChecks,
         state: input.state,
-        terminalSchedulerMeasurement: input.graphRun.terminalMeasurement
+        ...(terminalSchedulerMeasurement === undefined ? {} : { terminalSchedulerMeasurement })
       });
     }
     assertEveryCheckClosed(input.allChecks, input.graphRun.settlements);
@@ -88,12 +90,12 @@ export function closeCancelledExecution(
 }
 
 export function checkIdentity(
-  check: Pick<NormalizedCheck, "definition" | "visibility">
+  check: Pick<NormalizedCheck, "definition" | "omitQuietPassedRow">
 ): CheckIdentity {
   return Object.freeze({
     checkId: check.definition.checkId,
     displayName: check.definition.displayName,
-    visibility: check.visibility
+    omitQuietPassedRow: check.omitQuietPassedRow
   });
 }
 

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

@@ -1,11 +1,16 @@
-import type { CheckMessage, CheckOutcome, CheckVisibility } from "../../check/check.ts";
+import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { HandoffProviderIdentity } from "../../check/handoff-provider-identity.ts";
 import type { CoreCheckSession } from "../../check-settlement/session.ts";
 import {
   diagnosticTags,
   summarizeDiagnosticValue,
   type DiagnosticLogger
 } from "../diagnostic-logging/logger.ts";
-import { parseCheckTerminalResult } from "./terminal-result.ts";
+import {
+  diagnosticCallbackResult,
+  parseCheckTerminalResult,
+  type ParsedCheckTerminalHandoff
+} from "./terminal-result.ts";
 import { combineCheckMessages } from "./messages.ts";
 import type { CheckExecutionLifecycle } from "./lifecycle.ts";
 import type { executeCheckCallback } from "./callback.ts";
@@ -13,7 +18,7 @@ import type { executeCheckCallback } from "./callback.ts";
 export type CheckIdentity = Readonly<{
   readonly checkId: string;
   readonly displayName: string;
-  readonly visibility: CheckVisibility;
+  readonly omitQuietPassedRow: boolean;
 }>;
 
 export interface SettledCheckFacts {
@@ -22,9 +27,10 @@ export interface SettledCheckFacts {
 }
 
 export type CheckExecutionSettlementState = Readonly<{
-  readonly session: CoreCheckSession;
   readonly diagnosticLogger: DiagnosticLogger | undefined;
+  readonly handoffsByCheckId: Map<string, ParsedCheckTerminalHandoff>;
   readonly lifecycle: CheckExecutionLifecycle | undefined;
+  readonly session: CoreCheckSession;
   readonly settledFactsByCheckId: Map<string, SettledCheckFacts>;
 }>;
 
@@ -38,49 +44,102 @@ export class CheckExecutionInvariantFailure extends Error {
   }
 }
 
-export 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 }> {
+type SettleCallbackInput = Readonly<{
+  readonly callback: Awaited<ReturnType<typeof executeCheckCallback>>;
+  readonly checkId: string;
+  readonly diagnosticLogger: DiagnosticLogger | undefined;
+  readonly handoff: HandoffProviderIdentity | undefined;
+  readonly preparationMessages: readonly CheckMessage[];
+  readonly scope: ReturnType<CoreCheckSession["openCheckScope"]>;
+  readonly state: CheckExecutionSettlementState;
+}>;
+
+type SettledCallback = Readonly<{
+  readonly messages: readonly CheckMessage[];
+  readonly outcome: CheckOutcome;
+}>;
+type ProductCallback = Extract<SettleCallbackInput["callback"], { readonly source: "product" }>;
+type AuthorCallback = Extract<SettleCallbackInput["callback"], { readonly source: "author" }>;
+
+export function settleCallback(input: SettleCallbackInput): SettledCallback {
+  return input.callback.source === "product"
+    ? settleProductCallback(input, input.callback)
+    : settleAuthorCallback(input, input.callback);
+}
+
+/** Product-controlled callback failures settle without author-result parsing or handoff publication. */
+function settleProductCallback(
+  input: SettleCallbackInput,
+  callback: ProductCallback
+): SettledCallback {
+  const outcome = input.scope.settleProduct(callback.result);
+  return Object.freeze({
+    messages: combineCheckMessages(input.preparationMessages, callback.consoleMessages),
+    outcome
+  });
+}
+
+/** Parses an author result, settles it in Core, then commits its reference only after acceptance. */
+function settleAuthorCallback(
+  input: SettleCallbackInput,
+  callback: AuthorCallback
+): SettledCallback {
   const executionTags = diagnosticTags(`CHECK:${input.checkId}`, "EXECUTION");
-  const { callback } = input;
-  if (callback.source === "product") {
-    const outcome = input.scope.settleProduct(callback.result);
-    return Object.freeze({
-      messages: combineCheckMessages(input.preflightMessages, callback.consoleMessages),
-      outcome
-    });
-  }
-  const terminal = parseCheckTerminalResult(callback.result);
+  const terminal = parseCheckTerminalResult(callback.result, input.handoff);
   if (terminal === undefined) {
     input.diagnosticLogger?.observe({
       event: "callback.malformed",
       tags: diagnosticTags(...executionTags, "MALFORMED"),
-      details: { result: callback.result }
+      details: { result: diagnosticCallbackResult(callback.result, input.handoff) }
     });
   }
-  const settlement = input.scope.settle(terminal?.result ?? callback.result);
+  const settlement = input.scope.settle(
+    callbackSettlementCandidate(terminal, input.handoff, callback.result)
+  );
   if (terminal !== undefined && !settlement.authorResultAccepted) {
     input.diagnosticLogger?.observe({
       event: "check.contained",
       tags: diagnosticTags(...executionTags, "CONTAINED"),
-      details: { outcome: diagnosticOutcome(settlement.outcome), raw: callback.result }
+      details: { outcome: diagnosticOutcome(settlement.outcome), raw: terminal.result }
     });
   }
+  if (terminal?.handoff !== undefined && settlement.authorResultAccepted) {
+    commitAcceptedHandoff(input.checkId, terminal.handoff, input.state);
+  }
   return Object.freeze({
     messages:
       terminal !== undefined && settlement.authorResultAccepted
-        ? combineCheckMessages(input.preflightMessages, callback.consoleMessages, terminal.messages)
-        : combineCheckMessages(input.preflightMessages, callback.consoleMessages),
+        ? combineCheckMessages(
+            input.preparationMessages,
+            callback.consoleMessages,
+            terminal.messages
+          )
+        : combineCheckMessages(input.preparationMessages, callback.consoleMessages),
     outcome: settlement.outcome
   });
 }
 
+/** A declared callback never sends its raw result to Core when terminal parsing rejects the handoff. */
+function callbackSettlementCandidate(
+  terminal: ReturnType<typeof parseCheckTerminalResult>,
+  handoff: HandoffProviderIdentity | undefined,
+  rawResult: unknown
+): unknown {
+  if (terminal !== undefined) return terminal.result;
+  return handoff === undefined ? rawResult : undefined;
+}
+
+function commitAcceptedHandoff(
+  checkId: string,
+  handoff: ParsedCheckTerminalHandoff,
+  state: CheckExecutionSettlementState
+): void {
+  if (state.handoffsByCheckId.has(checkId)) {
+    throw new CheckExecutionInvariantFailure("Check handoff published more than once");
+  }
+  state.handoffsByCheckId.set(checkId, handoff);
+}
+
 /** Records one terminal Check lifecycle fact after its owning Core scope has closed. */
 export function recordSettledCheck(
   input: Readonly<{
@@ -88,7 +147,7 @@ export function recordSettledCheck(
     readonly durationMs: number | null;
     readonly messages: readonly CheckMessage[];
     readonly outcome: CheckOutcome;
-    readonly phase: "control" | "dependency" | "execution" | "preflight";
+    readonly phase: "control" | "dependency" | "execution" | "preparation";
     readonly state: CheckExecutionSettlementState;
   }>
 ): void {
@@ -122,7 +181,7 @@ export function recordSettledCheck(
       durationMs: input.durationMs,
       messages: input.messages,
       records: input.state.session.readSettledCheckRecords(input.check.checkId),
-      visibility: input.check.visibility
+      omitQuietPassedRow: input.check.omitQuietPassedRow
     })
   );
 }

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

@@ -1,9 +1,10 @@
+import type { CheckFlagCondition } from "../../check/check.ts";
 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 FlagControlledCheck = Pick<NormalizedCheck, "definition" | "omitQuietPassedRow">;
 type FlagControlOutcome = Readonly<{
   readonly status: "not-applicable";
   readonly reason: Readonly<{ readonly code: typeof FLAG_CONDITION_NOT_MATCHED_CODE }>;
@@ -85,7 +86,7 @@ function resolveFlagControl(
   return Object.freeze({
     check: Object.freeze({
       definition: check.definition,
-      visibility: check.visibility
+      omitQuietPassedRow: check.omitQuietPassedRow
     }),
     outcome: Object.freeze({
       status: "not-applicable",
@@ -118,15 +119,28 @@ function matchesFlagEnablement(
   enablement: NonNullable<NormalizedCheck["enabledByFlags"]>,
   runFlags: readonly string[]
 ): boolean {
-  const isPresentInRun = (flag: string): boolean => runFlags.includes(flag);
-  switch (enablement.mode) {
+  return matchesFlagCondition(enablement.when, new Set(runFlags));
+}
+
+function matchesFlagCondition(
+  condition: CheckFlagCondition,
+  runFlags: ReadonlySet<string>
+): boolean {
+  if (typeof condition === "string") return runFlags.has(condition);
+  switch (condition.kind) {
     case "all":
-      return enablement.flags.every(isPresentInRun);
+      return condition.conditions.every((child) => matchesFlagCondition(child, runFlags));
     case "any":
-      return enablement.flags.some(isPresentInRun);
+      return condition.conditions.some((child) => matchesFlagCondition(child, runFlags));
     case "none":
-      return !enablement.flags.some(isPresentInRun);
+      return !condition.conditions.some((child) => matchesFlagCondition(child, runFlags));
     case "not-all":
-      return !enablement.flags.every(isPresentInRun);
+      return !condition.conditions.every((child) => matchesFlagCondition(child, runFlags));
+    case "exactly-one":
+      return (
+        condition.conditions.filter((child) => matchesFlagCondition(child, runFlags)).length === 1
+      );
+    case "not":
+      return !matchesFlagCondition(condition.condition, runFlags);
   }
 }

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

@@ -1,15 +1,23 @@
-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";
 
-/** Private Run handoff for Check lifecycle presentation and accounting. */
+/** Private invocation-wide barrier that is independent from per-Check lifecycle facts. */
+export type InvocationLifecycle = Readonly<{
+  /** Fires once after Product accepts every flag-control settlement and before Scheduler work. */
+  readonly selectionSettled: () => void;
+}>;
+
+/** Private per-Check lifecycle presentation and accounting channel. */
 export type CheckExecutionLifecycle = Readonly<{
-  /** 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 CheckStartedFact = Readonly<{
+  checkId: string;
+  displayName: string;
+  omitQuietPassedRow: boolean;
+}>;
 
 export type CheckSettledFact = CheckStartedFact &
   Readonly<{
@@ -17,5 +25,5 @@ export type CheckSettledFact = CheckStartedFact &
     messages: readonly CheckMessage[];
     records: readonly CoreRecord[];
     outcome: CheckOutcome;
-    visibility: CheckVisibility;
+    omitQuietPassedRow: boolean;
   }>;