@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -1,18 +1,24 @@
-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 type { CheckExecutionLifecycle } from "./resolved-checks.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";
 
 export type CheckIdentity = Readonly<{
   readonly checkId: string;
   readonly displayName: string;
-  readonly visibility: CheckVisibility;
+  readonly omitQuietPassedRow: boolean;
 }>;
 
 export interface SettledCheckFacts {
@@ -22,10 +28,15 @@ export interface SettledCheckFacts {
 
 export type CheckExecutionSettlementState = Readonly<{
   readonly diagnosticLogger: DiagnosticLogger | undefined;
+  readonly handoffsByCheckId: Map<string, ParsedCheckTerminalHandoff>;
   readonly lifecycle: CheckExecutionLifecycle | undefined;
+  readonly session: CoreCheckSession;
   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);
@@ -33,46 +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: input.preflightMessages, 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
-        ? Object.freeze([...input.preflightMessages, ...terminal.messages])
-        : input.preflightMessages,
+        ? 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<{
@@ -80,7 +147,7 @@ export function recordSettledCheck(
     readonly durationMs: number | null;
     readonly messages: readonly CheckMessage[];
     readonly outcome: CheckOutcome;
-    readonly phase: "execution" | "preflight";
+    readonly phase: "control" | "dependency" | "execution" | "preparation";
     readonly state: CheckExecutionSettlementState;
   }>
 ): void {
@@ -101,7 +168,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,7 +180,8 @@ export function recordSettledCheck(
       outcome: input.outcome,
       durationMs: input.durationMs,
       messages: input.messages,
-      visibility: input.check.visibility
+      records: input.state.session.readSettledCheckRecords(input.check.checkId),
+      omitQuietPassedRow: input.check.omitQuietPassedRow
     })
   );
 }
@@ -121,13 +190,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,146 @@
+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" | "omitQuietPassedRow">;
+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,
+      omitQuietPassedRow: check.omitQuietPassedRow
+    }),
+    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 {
+  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 condition.conditions.every((child) => matchesFlagCondition(child, runFlags));
+    case "any":
+      return condition.conditions.some((child) => matchesFlagCondition(child, runFlags));
+    case "none":
+      return !condition.conditions.some((child) => matchesFlagCondition(child, runFlags));
+    case "not-all":
+      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

@@ -0,0 +1,29 @@
+import type { CheckMessage, CheckOutcome } from "../../check/check.ts";
+import type { CoreRecord } from "../../check-settlement/facts.ts";
+
+/** 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<{
+  readonly started: (fact: CheckStartedFact) => void;
+  readonly settled: (fact: CheckSettledFact) => void;
+}>;
+
+export type CheckStartedFact = Readonly<{
+  checkId: string;
+  displayName: string;
+  omitQuietPassedRow: boolean;
+}>;
+
+export type CheckSettledFact = CheckStartedFact &
+  Readonly<{
+    durationMs: number | null;
+    messages: readonly CheckMessage[];
+    records: readonly CoreRecord[];
+    outcome: CheckOutcome;
+    omitQuietPassedRow: boolean;
+  }>;

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)
   });
 }

package/src/project-run/check-execution/{preflight-result.ts → preparation-result.ts}

@@ -5,7 +5,7 @@ import {
 import type { CheckMessage } from "../../check/check.ts";
 import { parseCheckMessages } from "./messages.ts";
 
-export type ParsedCheckPreflightResult =
+export type ParsedCheckPreparationResult =
   | Readonly<{
       readonly status: "success";
       readonly preparedOptions: unknown;
@@ -25,30 +25,32 @@ export type ParsedCheckPreflightResult =
       readonly messages: readonly CheckMessage[];
     }>;
 
-/** Parses the closed result vocabulary returned by one trusted Check preflight. */
-export function parseCheckPreflightResult(value: unknown): ParsedCheckPreflightResult | undefined {
-  const preflightResult = snapshotClosedRecord(value);
-  if (preflightResult === undefined) {
+/** Parses the closed result vocabulary returned by one trusted Check preparation. */
+export function parseCheckPreparationResult(
+  value: unknown
+): ParsedCheckPreparationResult | undefined {
+  const preparationResult = snapshotClosedRecord(value);
+  if (preparationResult === undefined) {
     return undefined;
   }
-  const messages = parseCheckMessages(preflightResult.messages);
+  const messages = parseCheckMessages(preparationResult.messages);
   if (messages === undefined) return undefined;
-  switch (preflightResult.status) {
+  switch (preparationResult.status) {
     case "success":
-      return parseSuccessfulPreflight(preflightResult, messages);
+      return parseSuccessfulPreparation(preparationResult, messages);
     case "failure":
-      return parseFailedPreflight(preflightResult, messages);
+      return parseFailedPreparation(preparationResult, messages);
     default:
       return undefined;
   }
 }
 
-function parseSuccessfulPreflight(
-  preflightResult: Readonly<Record<string, unknown>>,
+function parseSuccessfulPreparation(
+  preparationResult: Readonly<Record<string, unknown>>,
   messages: readonly CheckMessage[]
-): ParsedCheckPreflightResult | undefined {
+): ParsedCheckPreparationResult | undefined {
   if (
-    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+    !hasRequiredAndOptionalRecordKeys(preparationResult, {
       optional: ["messages"],
       required: ["status", "preparedOptions"]
     })
@@ -57,35 +59,35 @@ function parseSuccessfulPreflight(
   }
   return Object.freeze({
     status: "success",
-    preparedOptions: preflightResult.preparedOptions,
+    preparedOptions: preparationResult.preparedOptions,
     messages
   });
 }
 
-function parseFailedPreflight(
-  preflightResult: Readonly<Record<string, unknown>>,
+function parseFailedPreparation(
+  preparationResult: Readonly<Record<string, unknown>>,
   messages: readonly CheckMessage[]
-): ParsedCheckPreflightResult | undefined {
-  if (typeof preflightResult.action !== "string") return undefined;
-  const reason = parsePreflightReason(preflightResult.reason);
+): ParsedCheckPreparationResult | undefined {
+  if (typeof preparationResult.action !== "string") return undefined;
+  const reason = parsePreparationReason(preparationResult.reason);
   if (reason === undefined) return undefined;
-  switch (preflightResult.action) {
+  switch (preparationResult.action) {
     case "block":
-      return parseBlockedPreflight(preflightResult, reason, messages);
+      return parseBlockedPreparation(preparationResult, reason, messages);
     case "continue":
-      return parseContinuedPreflight(preflightResult, reason, messages);
+      return parseContinuedPreparation(preparationResult, reason, messages);
     default:
       return undefined;
   }
 }
 
-function parseBlockedPreflight(
-  preflightResult: Readonly<Record<string, unknown>>,
+function parseBlockedPreparation(
+  preparationResult: Readonly<Record<string, unknown>>,
   reason: Readonly<{ readonly code: string }>,
   messages: readonly CheckMessage[]
-): ParsedCheckPreflightResult | undefined {
+): ParsedCheckPreparationResult | undefined {
   if (
-    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+    !hasRequiredAndOptionalRecordKeys(preparationResult, {
       optional: ["messages"],
       required: ["status", "action", "reason"]
     })
@@ -95,13 +97,13 @@ function parseBlockedPreflight(
   return Object.freeze({ status: "failure", action: "block", reason, messages });
 }
 
-function parseContinuedPreflight(
-  preflightResult: Readonly<Record<string, unknown>>,
+function parseContinuedPreparation(
+  preparationResult: Readonly<Record<string, unknown>>,
   reason: Readonly<{ readonly code: string }>,
   messages: readonly CheckMessage[]
-): ParsedCheckPreflightResult | undefined {
+): ParsedCheckPreparationResult | undefined {
   if (
-    !hasRequiredAndOptionalRecordKeys(preflightResult, {
+    !hasRequiredAndOptionalRecordKeys(preparationResult, {
       optional: ["messages"],
       required: ["status", "action", "fallback", "reason"]
     })
@@ -111,13 +113,13 @@ function parseContinuedPreflight(
   return Object.freeze({
     status: "failure",
     action: "continue" as const,
-    fallback: preflightResult.fallback,
+    fallback: preparationResult.fallback,
     reason,
     messages
   });
 }
 
-function parsePreflightReason(value: unknown): Readonly<{ readonly code: string }> | undefined {
+function parsePreparationReason(value: unknown): Readonly<{ readonly code: string }> | undefined {
   const reason = snapshotClosedRecord(value);
   if (
     reason === undefined ||