@zxyycom/vibe-check 0.0.1

package/src/project-definition/check-tree/resolution.ts

@@ -0,0 +1,108 @@
+import type { CheckDescriptor } from "../../check/descriptor.ts";
+import type { CheckExecution, CheckPreflight, CheckVisibility } from "../../check/check.ts";
+import {
+  parseCheckTreeAuthoring,
+  type MeaninglessCheckWarning,
+  type ParsedCheck,
+  type ParsedCheckCollection,
+  type ParsedCheckTree
+} from "./authoring.ts";
+
+export type { Check, InheritableCheckCollection } from "../../check/check.ts";
+
+export interface ResolvedCheckTreeLeaf {
+  readonly definition: CheckDescriptor;
+  readonly dependsOn: readonly string[];
+  readonly execution: CheckExecution;
+  readonly maxParallel: number;
+  readonly mutex: readonly string[];
+  readonly options: object;
+  readonly preflight?: CheckPreflight;
+  readonly visibility: CheckVisibility;
+}
+
+export interface ResolvedCheckTree {
+  readonly leaves: readonly ResolvedCheckTreeLeaf[];
+  readonly warnings: readonly MeaninglessCheckWarning[];
+}
+
+interface InheritedScheduling {
+  readonly dependsOn: readonly string[];
+  readonly maxParallel: number;
+  readonly mutex: readonly string[];
+}
+
+/**
+ * Traverses the recursive authoring tree. Containment only passes scheduling
+ * values to descendants; it never creates an execution dependency or output
+ * hierarchy.
+ */
+export function resolveCheckTree(
+  value: unknown,
+  rootMaxParallel: number
+): ResolvedCheckTree | undefined {
+  const parsed = parseCheckTreeAuthoring(value);
+  return parsed === undefined ? undefined : resolveParsedCheckTree(parsed, rootMaxParallel);
+}
+
+export function resolveParsedCheckTree(
+  parsed: ParsedCheckTree,
+  rootMaxParallel: number
+): ResolvedCheckTree | undefined {
+  if (!Number.isSafeInteger(rootMaxParallel) || rootMaxParallel <= 0) return undefined;
+  const leaves: ResolvedCheckTreeLeaf[] = [];
+  const root: InheritedScheduling = Object.freeze({
+    dependsOn: Object.freeze([]),
+    maxParallel: rootMaxParallel,
+    mutex: Object.freeze([])
+  });
+  for (const check of parsed.checks) flattenCheck(check, root, leaves);
+  return Object.freeze({ leaves: Object.freeze(leaves), warnings: parsed.warnings });
+}
+
+function flattenCheck(
+  check: ParsedCheck,
+  inherited: InheritedScheduling,
+  leaves: ResolvedCheckTreeLeaf[]
+): void {
+  const scheduling: InheritedScheduling = Object.freeze({
+    dependsOn: resolveCollection(inherited.dependsOn, check.dependsOn),
+    maxParallel: check.maxParallel ?? inherited.maxParallel,
+    mutex: resolveCollection(inherited.mutex, check.mutex)
+  });
+  const visibility = check.visibility;
+  if (
+    check.execution !== null &&
+    check.definition !== null &&
+    check.options !== null &&
+    visibility !== null
+  ) {
+    leaves.push(
+      Object.freeze({
+        definition: check.definition,
+        dependsOn: scheduling.dependsOn,
+        execution: check.execution,
+        maxParallel: scheduling.maxParallel,
+        mutex: scheduling.mutex,
+        options: check.options,
+        ...(check.preflight === null ? {} : { preflight: check.preflight }),
+        visibility
+      })
+    );
+  }
+  for (const child of check.checks) flattenCheck(child, scheduling, leaves);
+}
+
+function resolveCollection(
+  inherited: readonly string[],
+  authored: ParsedCheckCollection | undefined
+): readonly string[] {
+  if (authored === undefined) return inherited;
+  if (authored.kind === "exact") return canonicalize(authored.values);
+  const removed = new Set(authored.remove);
+  return canonicalize([...inherited.filter((value) => !removed.has(value)), ...authored.add]);
+}
+
+function canonicalize(values: readonly string[]): readonly string[] {
+  return Object.freeze([...new Set(values)].sort());
+}

package/src/project-definition/output-defaults.ts

@@ -0,0 +1,6 @@
+/** Default Run-owned output values applied when a Project Definition omits an override. */
+export const DEFAULT_PROJECT_OUTPUTS = Object.freeze({
+  machinePublication: Object.freeze({ directory: "artifacts/vibe-check", enabled: true }),
+  progressRendering: Object.freeze({ enabled: true }),
+  diagnosticLogging: Object.freeze({ directory: ".log/vibe-check", enabled: false })
+} as const);

package/src/project-definition/output-validation.ts

@@ -0,0 +1,54 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import type { ProjectOutputs } from "./project-definition.ts";
+import { snapshotClosedRecord } from "../data-boundary/closed-values.ts";
+
+const OUTPUT_NAMES = ["machinePublication", "progressRendering", "diagnosticLogging"] as const;
+const DIRECTORY_VALIDATION_ROOT = "/vibe-check-validation-root";
+
+export function parseOutputs(value: unknown): ProjectOutputs | undefined {
+  const data = exactKeys(value, OUTPUT_NAMES);
+  if (data === undefined) return undefined;
+  const machinePublication = parseDirectoryOutput(data.machinePublication);
+  const progressRendering = parseSwitchOutput(data.progressRendering);
+  const diagnosticLogging = parseDirectoryOutput(data.diagnosticLogging);
+  return machinePublication === undefined ||
+    progressRendering === undefined ||
+    diagnosticLogging === undefined ||
+    !isContainedRelativeDirectory(diagnosticLogging.directory)
+    ? undefined
+    : Object.freeze({ machinePublication, progressRendering, diagnosticLogging });
+}
+
+export function isContainedRelativeDirectory(directory: string): boolean {
+  if (directory.length === 0 || isAbsolute(directory)) return false;
+  const root = resolve(DIRECTORY_VALIDATION_ROOT);
+  const relativeDirectory = relative(root, resolve(root, directory));
+  return relativeDirectory !== ".." && !relativeDirectory.startsWith(`..${sep}`);
+}
+
+function parseDirectoryOutput(
+  value: unknown
+): Readonly<{ readonly directory: string; readonly enabled: boolean }> | undefined {
+  const data = exactKeys(value, ["directory", "enabled"]);
+  return typeof data?.directory === "string" && typeof data.enabled === "boolean"
+    ? Object.freeze({ directory: data.directory, enabled: data.enabled })
+    : undefined;
+}
+
+function parseSwitchOutput(value: unknown): Readonly<{ readonly enabled: boolean }> | undefined {
+  const data = exactKeys(value, ["enabled"]);
+  return typeof data?.enabled === "boolean" ? Object.freeze({ enabled: data.enabled }) : undefined;
+}
+
+function exactKeys(
+  value: unknown,
+  keys: readonly string[]
+): Readonly<Record<string, unknown>> | undefined {
+  const data = snapshotClosedRecord(value);
+  return data !== undefined &&
+    Object.keys(data).length === keys.length &&
+    keys.every((key) => Object.hasOwn(data, key))
+    ? data
+    : undefined;
+}

package/src/project-definition/project-definition-validation.ts

@@ -0,0 +1,123 @@
+import { resolveParsedCheckTree } from "./check-tree/resolution.ts";
+import { parseCheckTreeAuthoring } from "./check-tree/authoring.ts";
+import { materializeCheckTreeAuthoring } from "./check-tree/materialization.ts";
+import { parseOutputs } from "./output-validation.ts";
+import {
+  type ProjectDefinitionDiagnostic,
+  type ProjectDefinitionValidationResult,
+  type SchedulerPolicy
+} from "./project-definition.ts";
+import { snapshotClosedArray, snapshotClosedRecord } from "../data-boundary/closed-values.ts";
+
+type DefinitionValidationResult<T> = Readonly<
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: ProjectDefinitionDiagnostic }
+>;
+
+const PROJECT_DEFINITION_KEYS = ["apiVersion", "checks", "outputs", "scheduler"] as const;
+
+/**
+ * Validates one closed Definition before Run can invoke any project callback.
+ * Successful validation carries information-only Check warnings separately.
+ */
+export function validateProjectDefinition(value: unknown): ProjectDefinitionValidationResult {
+  try {
+    return validateProjectDefinitionValue(value);
+  } catch {
+    return invalidDefinition("definition");
+  }
+}
+
+function validateProjectDefinitionValue(value: unknown): ProjectDefinitionValidationResult {
+  const data = exactProjectDefinition(value);
+  if (!data.ok) return data;
+  return parseProjectDefinitionFields(data.value);
+}
+
+function parseProjectDefinitionFields(
+  data: Readonly<Record<string, unknown>>
+): ProjectDefinitionValidationResult {
+  const scheduler = parseScheduler(data.scheduler);
+  if (scheduler === undefined) return invalidDefinition("definition.scheduler");
+  const checks = snapshotClosedArray(data.checks);
+  if (checks === undefined) return invalidDefinition("definition.checks");
+  const parsedChecks = parseCheckTreeAuthoring(checks);
+  if (parsedChecks === undefined) return invalidDefinition("definition.checks");
+  const tree = resolveParsedCheckTree(parsedChecks, scheduler.maxParallel);
+  if (tree === undefined) return invalidDefinition("definition.checks");
+  const outputs = parseOutputs(data.outputs);
+  if (outputs === undefined) return invalidDefinition("definition.outputs");
+  return Object.freeze({
+    ok: true,
+    value: {
+      apiVersion: "1" as const,
+      checks: materializeCheckTreeAuthoring(parsedChecks),
+      outputs,
+      scheduler
+    },
+    warnings: tree.warnings
+  });
+}
+
+function exactProjectDefinition(
+  value: unknown
+): DefinitionValidationResult<Readonly<Record<string, unknown>>> {
+  const data = exactRecord(
+    value,
+    PROJECT_DEFINITION_KEYS,
+    "invalid-project-definition",
+    "definition"
+  );
+  if (!data.ok) return data;
+  return data.value.apiVersion === "1"
+    ? data
+    : invalid("invalid-project-definition", "definition.apiVersion", "invalid-value");
+}
+
+function exactRecord(
+  value: unknown,
+  allowedKeys: readonly string[],
+  kind: ProjectDefinitionDiagnostic["kind"],
+  path: string
+): DefinitionValidationResult<Readonly<Record<string, unknown>>> {
+  const data = snapshotClosedRecord(value);
+  if (data === undefined) return invalid(kind, path, "invalid-value");
+  const unknownKey = Object.keys(data).find((key) => !allowedKeys.includes(key));
+  if (unknownKey !== undefined) return invalid(kind, `${path}.${unknownKey}`, "unknown-key");
+  return Object.freeze({ ok: true, value: data });
+}
+
+function parseScheduler(value: unknown): SchedulerPolicy | undefined {
+  const data = exactKeys(value, ["maxParallel"]);
+  return typeof data?.maxParallel === "number" &&
+    Number.isSafeInteger(data.maxParallel) &&
+    data.maxParallel > 0
+    ? Object.freeze({ maxParallel: data.maxParallel })
+    : undefined;
+}
+
+function exactKeys(
+  value: unknown,
+  keys: readonly string[]
+): Readonly<Record<string, unknown>> | undefined {
+  const data = snapshotClosedRecord(value);
+  if (data === undefined) return undefined;
+  return Object.keys(data).length === keys.length && keys.every((key) => Object.hasOwn(data, key))
+    ? data
+    : undefined;
+}
+
+function invalidDefinition(path: string): ProjectDefinitionValidationResult {
+  return Object.freeze({
+    ok: false,
+    error: Object.freeze({ kind: "invalid-project-definition", path, reason: "invalid-value" })
+  });
+}
+
+function invalid(
+  kind: ProjectDefinitionDiagnostic["kind"],
+  path: string,
+  reason: ProjectDefinitionDiagnostic["reason"]
+): DefinitionValidationResult<never> {
+  return Object.freeze({ ok: false, error: Object.freeze({ kind, path, reason }) });
+}

package/src/project-definition/project-definition.ts

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+
+import { resolveCheckTree, type ResolvedCheckTreeLeaf } from "./check-tree/resolution.ts";
+import type { MeaninglessCheckWarning } from "./check-tree/authoring.ts";
+import type { CheckDescriptor } from "../check/descriptor.ts";
+import type { Check, CheckExecution, CheckPreflight, CheckVisibility } from "../check/check.ts";
+import { DEFAULT_PROJECT_OUTPUTS } from "./output-defaults.ts";
+import { isNonArrayRecord } from "../data-boundary/value-shapes.ts";
+
+/** 一次 Project Run 的明确输出配置。 */
+export interface ProjectOutputs {
+  /** `run.json` 与 `records.ndjson` publication。 */
+  readonly machinePublication: Readonly<{
+    /** 相对目录以 project root 解析，默认 `artifacts/vibe-check`。 */
+    readonly directory: string;
+    /** `false` 时本次 Run 不发布 machine output。 */
+    readonly enabled: boolean;
+  }>;
+  /** 人读 progress rendering。 */
+  readonly progressRendering: Readonly<{
+    /** `false` 时不构造或写入 progress writer。 */
+    readonly enabled: boolean;
+  }>;
+  /** 仅供维护者读取的一次 invocation diagnostic log。 */
+  readonly diagnosticLogging: Readonly<{
+    /** 相对目录以 project root 解析，默认 `.log/vibe-check`。 */
+    readonly directory: string;
+    /** `false` 时不创建 diagnostic writer 或 file。 */
+    readonly enabled: boolean;
+  }>;
+}
+
+/** 定义级的 Check 调度预算。 */
+export interface SchedulerPolicy {
+  readonly maxParallel: number;
+}
+/** 已补齐默认 outputs、可交给 run 执行的项目定义。 */
+export interface ProjectDefinition {
+  readonly apiVersion: "1";
+  readonly checks: readonly Check[];
+  readonly outputs: ProjectOutputs;
+  readonly scheduler: SchedulerPolicy;
+}
+type ProjectDefinitionInput = Readonly<{
+  apiVersion?: "1";
+  checks?: readonly Check[];
+  outputs?: Partial<{
+    machinePublication: Partial<ProjectOutputs["machinePublication"]>;
+    progressRendering: Partial<ProjectOutputs["progressRendering"]>;
+    diagnosticLogging: Partial<ProjectOutputs["diagnosticLogging"]>;
+  }>;
+  scheduler?: Partial<SchedulerPolicy>;
+}>;
+export interface ProjectDefinitionDiagnostic {
+  readonly kind: "invalid-project-definition";
+  readonly path: string;
+  readonly reason: "invalid-value" | "unknown-key";
+}
+export type DefinitionWarning = MeaninglessCheckWarning;
+export type ProjectDefinitionValidationResult = Readonly<
+  | {
+      readonly ok: true;
+      readonly value: ProjectDefinition;
+      readonly warnings: readonly DefinitionWarning[];
+    }
+  | { readonly ok: false; readonly error: ProjectDefinitionDiagnostic }
+>;
+export interface NormalizedCheckDeclaration {
+  readonly definition: CheckDescriptor;
+  readonly dependsOn: readonly string[];
+  readonly maxParallel: number;
+  readonly mutex: readonly string[];
+  readonly options: object;
+  readonly visibility: CheckVisibility;
+}
+export interface NormalizedCheck extends NormalizedCheckDeclaration {
+  readonly execution: CheckExecution;
+  readonly preflight?: CheckPreflight;
+}
+export interface DeclarativeProjectSnapshot {
+  readonly apiVersion: "1";
+  readonly checks: readonly NormalizedCheckDeclaration[];
+  readonly outputs: ProjectOutputs;
+  readonly scheduler: SchedulerPolicy;
+}
+export interface NormalizedProjectDefinition {
+  readonly checks: readonly NormalizedCheck[];
+  readonly declarative: DeclarativeProjectSnapshot;
+  readonly definitionWarnings: readonly DefinitionWarning[];
+}
+/** 使用 Product 默认输出创建普通 Project Definition。 */
+export function defineConfig<const T extends ProjectDefinitionInput>(
+  value: T & Record<Exclude<keyof T, keyof ProjectDefinitionInput>, never>
+): ProjectDefinition {
+  return {
+    apiVersion: value.apiVersion ?? "1",
+    checks: value.checks ?? [],
+    outputs: {
+      machinePublication: {
+        directory:
+          value.outputs?.machinePublication?.directory ??
+          DEFAULT_PROJECT_OUTPUTS.machinePublication.directory,
+        enabled:
+          value.outputs?.machinePublication?.enabled ??
+          DEFAULT_PROJECT_OUTPUTS.machinePublication.enabled
+      },
+      progressRendering: {
+        enabled:
+          value.outputs?.progressRendering?.enabled ??
+          DEFAULT_PROJECT_OUTPUTS.progressRendering.enabled
+      },
+      diagnosticLogging: {
+        directory:
+          value.outputs?.diagnosticLogging?.directory ??
+          DEFAULT_PROJECT_OUTPUTS.diagnosticLogging.directory,
+        enabled:
+          value.outputs?.diagnosticLogging?.enabled ??
+          DEFAULT_PROJECT_OUTPUTS.diagnosticLogging.enabled
+      }
+    },
+    scheduler: { maxParallel: value.scheduler?.maxParallel ?? 4 }
+  };
+}
+export function normalizeProjectDefinition(
+  definition: ProjectDefinition
+): NormalizedProjectDefinition {
+  const tree = resolveCheckTree(definition.checks, definition.scheduler.maxParallel);
+  if (tree === undefined)
+    throw new TypeError("Project Definition Check tree failed closed normalization");
+  const checks = Object.freeze(tree.leaves.map(normalizeCheck));
+  return Object.freeze({
+    checks,
+    declarative: freezeDeclarativeSnapshot(definition, checks),
+    definitionWarnings: tree.warnings
+  });
+}
+function normalizeCheck(leaf: ResolvedCheckTreeLeaf): NormalizedCheck {
+  return Object.freeze({
+    definition: leaf.definition,
+    dependsOn: leaf.dependsOn,
+    execution: leaf.execution,
+    maxParallel: leaf.maxParallel,
+    mutex: leaf.mutex,
+    options: leaf.options,
+    ...(leaf.preflight === undefined ? {} : { preflight: leaf.preflight }),
+    visibility: leaf.visibility
+  });
+}
+export function createDeclarativeFingerprint(snapshot: DeclarativeProjectSnapshot): string {
+  return createHash("sha256").update(stableJson(snapshot)).digest("hex");
+}
+function freezeDeclarativeSnapshot(
+  definition: ProjectDefinition,
+  checks: readonly NormalizedCheck[]
+): DeclarativeProjectSnapshot {
+  const declarations = checks
+    .map(({ execution: _execution, preflight: _preflight, ...declaration }) => declaration)
+    .sort((left, right) => compareText(left.definition.checkId, right.definition.checkId));
+  return deepFreeze({
+    apiVersion: definition.apiVersion,
+    checks: declarations,
+    outputs: definition.outputs,
+    scheduler: definition.scheduler
+  });
+}
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+  for (const item of Object.values(value)) deepFreeze(item);
+  return Object.freeze(value);
+}
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (isNonArrayRecord(value))
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  return JSON.stringify(value);
+}

package/src/project-run/aggregation.ts

@@ -0,0 +1,90 @@
+import type {
+  RunControlDiagnostic,
+  RunControlValidationResult
+} from "./controls/validation-result.ts";
+import type { CheckAggregate, CheckAggregation } from "./controls/contract.ts";
+import type { CoreCheck, CoreSnapshot } from "../check-settlement/facts.ts";
+
+type AggregateStatus = Exclude<CheckAggregate, "not-applicable">;
+
+/** Validates that aggregation selects only normalized executable Check IDs. */
+export function validateCheckAggregationSelection(
+  aggregation: CheckAggregation | undefined,
+  checkIds: readonly string[]
+): RunControlValidationResult<CheckAggregation | undefined> {
+  if (aggregation === undefined) return Object.freeze({ ok: true, value: undefined });
+  if (aggregation.checks === "all") return Object.freeze({ ok: true, value: aggregation });
+  const knownCheckIds = new Set(checkIds);
+  const selectedCheckIds = new Set<string>();
+  for (const checkId of aggregation.checks) {
+    if (!knownCheckIds.has(checkId) || selectedCheckIds.has(checkId)) {
+      return invalidControls("controls.checkAggregation.checks");
+    }
+    selectedCheckIds.add(checkId);
+  }
+  return Object.freeze({ ok: true, value: aggregation });
+}
+
+/** Derives one explicit consumer-selected aggregate from settled Check statuses only. */
+export function aggregateCheckOutcomes(
+  snapshot: CoreSnapshot,
+  aggregation: CheckAggregation
+): CheckAggregate {
+  const statuses = selectedChecks(snapshot, aggregation.checks).map((check) =>
+    aggregateStatus(check, aggregation)
+  );
+  if (statuses.includes("unavailable")) return "unavailable";
+  return aggregateSelectedStatuses(
+    statuses.filter(
+      (status): status is Exclude<AggregateStatus, "unavailable"> =>
+        status !== null && status !== "unavailable"
+    ),
+    aggregation
+  );
+}
+
+function selectedChecks(
+  snapshot: CoreSnapshot,
+  selection: CheckAggregation["checks"]
+): readonly CoreCheck[] {
+  if (selection === "all") return snapshot.checks;
+  return selection.map((checkId) => {
+    const check = snapshot.checks.find((candidate) => candidate.checkId === checkId);
+    if (check === undefined) throw new TypeError("Aggregation selection was not validated");
+    return check;
+  });
+}
+
+function aggregateStatus(check: CoreCheck, aggregation: CheckAggregation): AggregateStatus | null {
+  switch (check.outcome.status) {
+    case "passed":
+    case "failed":
+      return check.outcome.status;
+    case "unavailable": {
+      if (aggregation.unavailable === "propagate") return "unavailable";
+      return aggregation.unavailable === "fail" ? "failed" : null;
+    }
+    case "not-applicable": {
+      if (aggregation.notApplicable === "pass") return "passed";
+      return aggregation.notApplicable === "fail" ? "failed" : null;
+    }
+  }
+}
+
+function aggregateSelectedStatuses(
+  statuses: readonly Exclude<AggregateStatus, "unavailable">[],
+  aggregation: CheckAggregation
+): CheckAggregate {
+  if (statuses.length === 0) return aggregation.empty;
+  if (aggregation.mode === "all") return statuses.includes("failed") ? "failed" : "passed";
+  return statuses.includes("passed") ? "passed" : "failed";
+}
+
+function invalidControls(path: string): RunControlValidationResult<never> {
+  const error: RunControlDiagnostic = Object.freeze({
+    kind: "invalid-run-controls",
+    path,
+    reason: "invalid-value"
+  });
+  return Object.freeze({ ok: false, error });
+}

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

@@ -0,0 +1,106 @@
+import type {
+  CheckDependencies,
+  CheckExecutionContext,
+  CheckOutcome,
+  CheckProjectContext
+} from "../../check/check.ts";
+import type { NormalizedCheck } from "../../project-definition/project-definition.ts";
+import { CoreInvariantFailure, type TrustedCheckScope } from "../../check-settlement/session.ts";
+import { diagnosticTags, type DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+
+export type CallbackExecution = Readonly<
+  | {
+      /** Raw author result; Core owns its sole validation and canonicalization. */
+      readonly source: "author";
+      readonly result: unknown;
+    }
+  | {
+      /** Only callback containment may create a Product-controlled outcome. */
+      readonly source: "product";
+      readonly result: CheckOutcome;
+    }
+>;
+
+interface CheckCallbackInput {
+  readonly check: NormalizedCheck;
+  readonly dependencies: CheckDependencies;
+  readonly diagnosticLogger?: DiagnosticLogger;
+  readonly project: CheckProjectContext;
+  readonly scope: TrustedCheckScope;
+  readonly signal: AbortSignal;
+}
+
+interface CheckReporterLifecycle {
+  readonly records: CheckExecutionContext<object>["records"];
+  close(): void;
+}
+
+/** Runs one trusted callback and closes its Check-owned reporter before return. */
+export async function executeCheckCallback(input: CheckCallbackInput): Promise<CallbackExecution> {
+  const checkId = input.check.definition.checkId;
+  const checkTags = diagnosticTags(`CHECK:${checkId}`, "EXECUTION");
+  const reporter = createCheckReporter(input.scope, input.diagnosticLogger, checkTags);
+  let result: CallbackExecution;
+  try {
+    const context = Object.freeze({
+      dependencies: input.dependencies,
+      options: input.check.options,
+      project: input.project,
+      records: reporter.records,
+      signal: input.signal
+    });
+    const callbackResult = await input.check.execution(context);
+    if (input.signal.aborted) {
+      input.diagnosticLogger?.observe({
+        event: "callback.cancelled",
+        tags: diagnosticTags(...checkTags, "CANCELLED"),
+        details: { result: callbackResult }
+      });
+    }
+    result = input.signal.aborted
+      ? productResult("execution-cancelled")
+      : Object.freeze({ source: "author", result: callbackResult });
+  } catch (error) {
+    if (error instanceof CoreInvariantFailure) throw error;
+    input.diagnosticLogger?.observe({
+      event: input.signal.aborted ? "callback.cancelled" : "callback.threw",
+      tags: diagnosticTags(...checkTags, input.signal.aborted ? "CANCELLED" : "THREW"),
+      details: { error }
+    });
+    result = productResult(input.signal.aborted ? "execution-cancelled" : "execution-threw");
+  } finally {
+    reporter.close();
+  }
+  return result;
+}
+
+function createCheckReporter(
+  scope: TrustedCheckScope,
+  diagnosticLogger: DiagnosticLogger | undefined,
+  checkTags: readonly string[]
+): CheckReporterLifecycle {
+  let isOpen = true;
+  return Object.freeze({
+    close: (): void => {
+      isOpen = false;
+    },
+    records: Object.freeze({
+      report: (identity: unknown, data: unknown): void => {
+        if (!isOpen) throw new Error("Check record reporter is closed");
+        const result = scope.records.report(identity, data);
+        diagnosticLogger?.observe({
+          event: "record.reported",
+          tags: diagnosticTags(...checkTags, "RECORD", result.toUpperCase()),
+          details: { data, identity, result }
+        });
+      }
+    })
+  });
+}
+
+function productResult(code: string): CallbackExecution {
+  return Object.freeze({
+    source: "product",
+    result: Object.freeze({ status: "unavailable", reason: Object.freeze({ code }) })
+  });
+}